Hosts and keys

Base URL

Every call goes to this address over HTTPS:

https://api.luxorr.io/v1

Keys

A key is lxr_live_ followed by 32 random characters:

Authorization: Bearer lxr_live_7Hk2…

Keep these rules in mind:

• The key is shown only once. Luxorr can’t show it to you again. If you lose a key, create a new one and revoke the old one.
• Use the key only on your servers. Call the API from your servers. Never put a key in a browser, an app, or a repository.

What a key can access

A key belongs to one Luxorr account, which the API calls the tenant. If your key can’t access a record, the API returns 404 not_found.

A key can access every brand of your account, including brands that are added later, or only some brands. GET /me lists the key’s brands in brands. A key that is limited to some brands works as follows:

• It sees only the links, campaigns, rewards stores, store orders, and events of those brands.
• It gets 404 not_found for a link or a store order of another brand.
• It can’t create a link or place an order for another brand.

A key sees only the store orders that it placed. If another of your keys placed an order, the API returns 404 not_found for that order.

Scopes

A scope defines what a key can do. GET /me lists the key’s scopes in key.scopes:

{ "key": { "name": "Player shop", "scopes": ["PERSONAL_LINKS", "REWARD_STORES"], "webhookUrl": "https://hooks.operator.example/luxorr" } }

The following table lists what each scope allows:

Scope	Calls and events
PERSONAL_LINKS	/campaigns, /personal-links, and personal_link.* events
REWARD_STORES	/reward-stores, /reward-store-orders, and order.* events

Your Administrator or Luxorr selects the scopes in the key form. A new key starts with PERSONAL_LINKS selected. A key has one scope or both. If a call needs a scope that the key doesn’t have, the API returns 403 insufficient_scope. The key also gets no events of that scope.

Manage keys

Your Administrator manages keys in the Luxorr workspace, in Settings > API access. Luxorr can also do this for you. On that page, the Administrator can do the following:

• Name a key and limit it to some brands.
• Choose the key’s scopes.
• Set the webhook URL, send a test event, and see recent deliveries.
• Rotate the webhook signing secret.
• Revoke the key. A revoked key is refused from the next call.

Use one key for each system, for example one for the CRM and one for the shop. You can revoke each key on its own. A key cancels only the links that it created, and sees only the store orders that it placed. Your team sees which key created what.

API access switch

API access is off for your account until Luxorr turns it on. Only Luxorr changes this setting, and your Administrators get an email each time it changes.

While API access is off, the following applies:

• Every key returns 401 invalid_api_key.
• Webhooks pause, but events are still recorded.
• Keys can’t be created, changed, or tested, and webhook secrets can’t be rotated.

Administrators can still see keys and webhook deliveries, and revoke keys. When API access is turned on again, the same keys work and the paused webhooks are sent.

If a working key starts to return 401, the key was revoked or API access was turned off.