Connecting partners

Send partners to Localoy with a deep link, take the one-time connection code they generate, claim it, and follow the connection as the partner changes it.

A partner connects you itself, in its Partner Portal. Your part is to send it there, and to claim the code it brings back.

Connecting a partner

1. Send the partner a deep link#

Deep link

https://partner.localoy.app/dashboard/open-network/providers?connect={providerKey}

{providerKey} is your permanent provider key — GET /ping returns it as provider.key. The link takes the partner to you on its Open Network → Technology Providers page. It works whether or not Localoy lists you, as long as you are not suspended.

Put it behind a Connect to Localoy button in your product's settings, beside the field where the partner will paste its code.

2. The partner generates a code#

On that page the partner sees your name, logo, description, website, support email and the modules you serve, and one choice for each scope Localoy allows you to ask for, with its consent text. It ticks what it grants and generates a connection code.

Rule on the partner's side	Detail
Partner+	Generating a code needs an active Partner+ subscription with the Open Network benefit.
Its own consent	Localoy staff signed in as the partner cannot generate a code or add a scope.
One live connection	A partner already connected to you changes your access instead of generating a new code.
Rate	10 codes per 15 minutes per partner.

Tell partners which scopes you need before they start. They choose; you cannot tick anything for them.

The connection code#

Connection code

LCC-7K2M-9QXT-4VBN-H3WP

Property	Value
Format	`LCC-` and four groups of four characters.
Lifetime	15 minutes from when the partner generates it.
Use	Once.
Shown	Once, to the partner. Localoy keeps only a hash of it.
Replaced	Generating a new code stops the previous one from working.

When you send a code, case, spaces and hyphens do not matter, and the LCC- prefix is optional. These are the same code:

Equivalent forms

LCC-7K2M-9QXT-4VBN-H3WP
lcc 7k2m 9qxt 4vbn h3wp
7K2M9QXT4VBNH3WP

Accept whatever the partner pastes and send it as it is. Never store a code, and never log it.

3. Claim the code#

cURL

curl -X POST "$LOCALOY_BASE_URL/connections/claim" \
  -H "Authorization: Bearer $LOCALOY_PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "LCC-7K2M-9QXT-4VBN-H3WP" }'

Answer	Meaning
`201`	Claimed. `data` is the new connection.
`200`	You had already claimed this code, and it has not expired. `data` is the same connection.
`404 connection_code_invalid`	The code is unknown, expired or already used, belongs to another provider, or its connection was disconnected — one answer for all. Ask the partner for a new code.
`429 connection_claim_rate_limited`	More than 20 claims in 15 minutes with this key. Wait for `Retry-After`.

A claim needs no partner header: the code says which partner it is for.

Claiming is idempotent for you. If a claim's response is lost, send the same code again:

Retrying a claim

What to store#

Field	Why
`partnerId`	Send it as `X-Localoy-Partner-Id` on every call for this partner, and route its webhooks by it. Keep it against the partner's account in your system.
`id`	The connection's ID, for support conversations.
`scopes`	What you may do for this partner now. Refresh it on every `connection.updated`.
`modules`	Which bookables, payment sessions and bookings you will see.
`partner.name`	To show which Localoy account was connected.

After the claim, compare scopes with what your integration needs. If something is missing, ask the partner to add it on its Open Network → Technology Providers page. That needs no new code, but adding a scope needs the partner's Partner+ subscription and its own sign-in.

Connection statuses#

Status	Means	Your calls for the partner	Its webhooks
`ACTIVE`	Connected.	Allowed, within effective scopes.	Delivered.
`PAUSED`	The partner paused you.	`403 connection_paused`	None after the `connection.updated` that announces it.
`REVOKED`	The partner disconnected you.	`404 connection_not_found`	None after `connection.revoked`.

A code the partner generated but you have not claimed is not a connection for you: calls for that partner answer 404 connection_not_found, and it is not listed.

When the partner changes the connection#

Pause, scope change and disconnect

The partner	Needs Partner+	You receive	Then
Pauses you	No	`connection.updated`, reason `paused`	Calls answer `403 connection_paused`, and nothing else is delivered for the partner.
Resumes you	Yes	`connection.updated`, reason `resumed`	Calls and deliveries work again.
Adds a scope	Yes	`connection.updated`, reason `scopes_changed`	The scope works from the next call.
Removes a scope	No	`connection.updated`, reason `scopes_changed`	Calls that need it answer `403 open_network_scope_required`.
Disconnects you	No	`connection.revoked`, reason `disconnected_by_partner`	Access ends at once, any outstanding code stops working, and the items you created for the partner are removed.

A scopes_changed event carries previousScopes, and connection.revoked carries itemsRemoved. See Connection events.

To connect again after a disconnect, the partner generates a new code and you claim it, as the first time.

Keeping your records in step#

GET /connections lists your active and paused connections; add ?status=revoked for the ones that ended. Use it to reconcile with your own records — for example after your webhook endpoint has been down.