Authentication

Every call you make is authenticated with a provider key that Localoy issues to your company. A call made for a partner also names that partner in the X-Localoy-Partner-Id header.

Key format#

ltp_{environment}_{prefix}_{secret}

A sandbox key is 60 characters long and a production key 61. The first three parts together — ltp_sbx_k7m2q9xa — are the key's public prefix: GET /ping returns it, so you can tell keys apart without exposing the secret.

Localoy stores only a SHA-256 hash of each key. A key is shown once, when Localoy issues it, and cannot be recovered afterwards. Localoy can also give a key an expiry date; after it, the key is refused.

Sending the key#

Send the key in either header:

Authorization: Bearer ltp_live_r4t8wz3c_…

X-Api-Key: ltp_live_r4t8wz3c_…

If a request carries both, the Authorization header is used.

Which routes a key can call#

The catalogue, bookables and payment endpoints are the partner-scoped endpoints. The connection and webhook endpoints act for your company, not for a partner.

The partner header#

X-Localoy-Partner-Id: cm1partnerid000000000000001

Send it on every partner-scoped call. Its value is the partnerId of a connection you claimed. Localoy then checks that connection:

{
  "success": false,
  "message": "That partner is not connected to you. A partner connects you by giving you a connection code to claim.",
  "code": "connection_not_found",
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}

connection_not_found answers every partner you are not connected to in the same way, so it never confirms that an ID belongs to a real partner.

Effective scopes#

Each partner-scoped endpoint needs one scope, as in the Open Network API: REGISTRATION to create items, UPDATE to change or delete them, INVENTORY to read items and bookables, and PAYMENT for payment sessions. For you, the check uses the connection's effective scopes — what the partner granted that Localoy still allows you. See Effective scopes.

{
  "success": false,
  "message": "This partner has not granted you the UPDATE scope, which this endpoint requires.",
  "code": "open_network_scope_required",
  "details": {
    "requiredScope": "UPDATE",
    "grantedScopes": ["REGISTRATION", "INVENTORY"]
  },
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}

details.grantedScopes holds the effective scopes. Do not retry: tell the partner which permission is missing. It can add a scope in its Partner Portal without a new code.

Verifying a key#

GET /ping accepts a provider key and needs no partner header:

{
  "success": true,
  "data": {
    "ok": true,
    "principal": "TECHNOLOGY_PROVIDER",
    "environment": "PRODUCTION",
    "keyPrefix": "ltp_live_r4t8wz3c",
    "provider": { "key": "example-pos", "name": "Example POS" }
  }
}

Send X-Localoy-Partner-Id as well and /ping checks that connection the way a partner-scoped call does — with the 400, 404 and 403 answers in the table above — though it needs no scope. For an active connection the response adds the partnerId, the connection's id and status, and your effective scopes for it: a quick check before a sync.

{
  "success": true,
  "data": {
    "ok": true,
    "principal": "TECHNOLOGY_PROVIDER",
    "environment": "PRODUCTION",
    "keyPrefix": "ltp_live_r4t8wz3c",
    "provider": { "key": "example-pos", "name": "Example POS" },
    "partnerId": "cm1partnerid000000000000001",
    "connection": { "id": "cm7c0nn3ct10n00000000001", "status": "ACTIVE" },
    "scopes": ["REGISTRATION", "UPDATE", "INVENTORY"]
  }
}

When a key is refused#

A missing, malformed, unknown, revoked or expired key, or one with the wrong secret, gets one answer, whatever the reason:

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "open_network_key_invalid",
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}

The response never says why, so it cannot help someone guessing keys. Compare the key's public prefix with the one Localoy gave you; if it still fails, send the requestId to your partnerships contact.

Errors#

Every provider error is listed in Errors.

Rotating a key without downtime#

Localoy issues and revokes your keys, so replacing one is a request to your partnerships contact:

1. Ask for a second key in the same environment. You can hold up to 5 live keys in each.
2. Deploy it everywhere the old key is used.
3. Confirm that traffic has moved: GET /ping returns the new key's keyPrefix.
4. Ask Localoy to revoke the old key. It stops working on its next request.

If a key has leaked, do not wait for a replacement: ask Localoy to revoke it at once.

Calling from a server only#