Authentication

Every Partner API request carries one credential, in the standard place:

Authorization: Bearer brp_<prefix>.<secret>

There is no other scheme. No query-string key, no basic auth, no cookie. A request without that header, or with a malformed value, answers 401 before anything else is evaluated.

What a key is

A key has two halves separated by a dot.

BackResto stores the prefix and a keyed digest of the secret. The secret itself is not stored and cannot be recovered — not by you, not by support, not from the database. If it is lost, revoke the key and create another.

Grants: restaurant × scope

A key is not "an account with permissions". It is a list of explicit grants, each one a pair:

There are twenty-six scopes, and the grammar is worth learning once:

Every scope ends in :read. There is no partner scope that writes, and none can be created: the write side of this API belongs to the BackResto app, and a partner key is structurally incapable of holding one.

A key granted deliveries:read on restaurant-1 and restaurant-2, and delivery-images:read on restaurant-1 only, reads photographs for the first restaurant and gets 403 for the second. That is a supported configuration, not a mistake — some integrations want the records without the pictures.

Ask for what you use. Twenty-six scopes is not a menu to tick through: the restaurant reads the list before agreeing to it, and a request for everything takes longer to get through than a request for the four collections your product actually reads.

Three failure modes, deliberately distinct:

• 404 — the key holds no grant at all for that restaurant. The API does not tell an unauthorised caller whether a restaurant exists.
• 403 — the key holds a grant for that restaurant, but not the scope this endpoint needs.
• 401 — among other things, a key with no grants left at all. A key stripped of its last grant stops authenticating rather than answering empty.

To see what a key actually holds, ask it: GET /v1/restaurants lists the restaurants with their scopes, and GET /v1/restaurants/{id}/collections lists the collections it opens.

Who can issue one

We do, on request, and only for restaurants that have agreed to it. See Getting a key for what to send and what comes back.

Grants are set when the key is provisioned and changed only by another request. There is no path — for you or for us — that widens a key without the restaurant agreeing to it again.

Expiry and revocation

A key does not expire on its own unless you asked for one that does. It stays valid until it is revoked.

Revocation is immediate: the next request with that key answers 401, the same answer an unknown or expired key gets. It cannot be undone, and it does not need to be — a replacement is a new key, not a restored one.

Rotating without downtime

An integration can hold two live keys at once, so rotation needs no maintenance window. Ask us to rotate and this is the order it happens in:

1. We issue a second key with the same restaurants and scopes.
2. You deploy the new secret, and tell us when it is live everywhere.
3. We check that the old key has stopped being used — we can see when each key last authenticated, which is the signal that makes step 4 safe.
4. We revoke the old one.

Rotate on a schedule you choose, and start the request a few days before you want the old key gone: steps 2 and 3 are yours and ours to co-ordinate, and the whole point of the order above is that nothing is ever briefly dead.

Hygiene

• Store it on arrival and delete the email. The secret exists in exactly two places once that is done: your secret manager, and the Authorization header.
• One key per deployment, not one per company. A leaked staging key should never be a production incident, and a revocation should never take down more than the thing that leaked.
• Never send us the secret — not in a ticket, not to identify a key. The public prefix names it unambiguously and is safe to write anywhere.
• Watch for 401 in your own monitoring. A key that starts failing has been revoked, and the answer is a conversation, not a retry loop.