How it works

The three parties, the difference between your keys and your connections, the scopes partners grant, the modules you serve, and the life of a connection.

Three parties#

Party	Who	Role
Localoy	Runs the Open Network.	Registers your company as a Technology Provider and issues your keys. Decides which scopes you may ask for and which modules you serve. Can suspend you.
Partner	A business on Localoy that uses your platform.	Connects you from its Partner Portal and chooses the scopes it grants. Can pause you, change your access or disconnect you at any time.
Technology Provider	Your company.	Claims the partner's connection code, then calls the Open Network API for that partner, within what it granted.

The partner stays in charge of its own account. Every call you make for a partner appears on its Open Network → Activity page, under your name.

Keys and connections#

	Your key	A connection
Answers	Who is calling: your company.	For whom: one partner, and what it allowed.
Created by	Localoy, when you ask for it.	The partner's consent — you claim the code it generates.
Sent as	`Authorization: Bearer ltp_…`	`X-Localoy-Partner-Id: {partnerId}`
How many	Up to 5 live keys per environment.	One live connection per partner.
Ends when	Localoy revokes it, or it expires.	The partner disconnects you.

A call for a partner needs both. Your key alone can do nothing for a partner, and a partnerId alone is only an identifier.

A connection has no environment. It is between your company and the partner, whichever key claimed it; the key you send on each call decides whether that call runs in the sandbox or in production. See Sandbox and production.

Scopes#

A partner grants you scopes. Four are the scopes of the Open Network API. The fifth, BOOKINGS, exists only for Technology Providers: a partner's own API key cannot hold it.

The partner reads the text below, word for word, when it chooses. Two scopes share customers' personal data, and their text says so.

Scope	The partner reads	Personal data	It lets you
`REGISTRATION`	Add items to your catalogue. Create catalogue items on Localoy for you, and link them to your tickets, activities or tables.	No	Create items.
`UPDATE`	Change and remove its items. Update the price, stock and details of the items it created for you, or remove them. It cannot touch items you or another provider created.	No	Update and delete your items.
`INVENTORY`	Read its items and your bookables. See the catalogue items it manages for you, and the tickets, activities and tables it can link them to.	No	List and read your items; list bookables.
`PAYMENT`	Handle payments for your bookings. Read payment sessions — including the customer's name, phone and email — and report whether a customer paid or was refunded.	Yes	Read sessions, report results and record refunds.
`BOOKINGS`	See your bookings. Receive your bookings as they happen, including each customer's name, phone and email.	Yes	Receive `booking.*` webhooks; with `PAYMENT`, `payment.updated`.

Localoy decides which of the five you may ask for. The partner sees only those, ticks the ones it grants, and can add or remove scopes later without a new code.

Ask only for what your integration uses, and tell partners which scopes you need before they connect: they choose from the list, and you cannot tick anything for them.

Effective scopes#

What you can do for a partner at any moment is its effective scopes: the scopes it granted that Localoy still allows you.

Rule

effective scopes = scopes the partner granted ∩ scopes Localoy allows you

For example, if Localoy withdraws PAYMENT from your allowed scopes after a partner granted it:

	`REGISTRATION`	`UPDATE`	`INVENTORY`	`PAYMENT`
Localoy allows you	Yes	Yes	Yes	No
The partner granted	Yes	No	Yes	Yes
Effective	Yes	No	Yes	No

The connection's scopes, GET /ping with a partner header, and the details.grantedScopes of a 403 open_network_scope_required all report effective scopes. The connection's grantedScopes is what the partner ticked. A change to either side applies from the next call.

Modules#

Localoy registers the modules you serve. Whatever a partner grants, they narrow what you see of it:

Module	Partners see	Bookables you can link	Payment sessions you can read	Bookings you receive
`EVENT`	Events	`event_ticket`	`EVENT_TICKET_ORDER`	`module` `event`
`DINING`	Dining	`dining`	`DINING_RESERVATION`	`module` `dining`
`ACTIVITY`	Activities	`activity_item`	`ACTIVITY_BOOKING`	`module` `activity`

Outside your modules, GET /bookables leaves a bookable out, a payment session answers 404, and a booking sends you no webhook. Catalogue items themselves belong to no module.

The life of a connection#

A connection from code to disconnect

Status	What it 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 yet: calls for that partner answer 404 connection_not_found until you claim it. See Connecting partners.