Four principals, four shapes
Every/flynet/v1 route answers to exactly one principal. The principal
decides the credential, the path shape, and the scope family.
One URL never serves two principals. A member reading their own passes
calls
/users/me/passes; a venue reading the passes it is on calls
/venues/me/passes. Same resource, different principal, different
route. me always means the caller’s own estate, resolved from the
token, never a path parameter.
Who the token represents
A restaurant-user token names a person, not a location.- The token’s
subis the staff member’s restaurant user id. Aprincipal_type: RESTAURANT_USERclaim says which population the id belongs to, so the API never has to guess whether a bare UUID is a diner or a staff member. - Which locations that person may act on is not in the token. The API reads their current location memberships on every request. Remove a staff member from a location and their existing tokens stop working there immediately. Add one and no re-authorization is needed.
- Two staff at the same restaurant authorize your app separately and revoke separately. A manager disconnecting your app does not disconnect a colleague’s grant.
Scopes
Restaurant-user scopes carry arestaurant_ prefix. Each binds to the
restaurant-user credential only: it cannot be minted onto an API key, and
it cannot share a token with a diner scope.
Tasting note - Requesting a restaurant scope is how you ask for a
staff sign-in. There is no separate parameter. The
/authorize endpoint
derives the required principal from the scope set: ask for
read:restaurant_profile and the consent screen offers a staff login;
ask for read:profile and it offers a diner login. A scope set that
spans both populations is rejected with invalid_scope, because one
token has one principal.The flow
Same four steps as member OAuth. The differences are marked.Step 1 - Authorize with restaurant scopes
All seven parameters are required, exactly as for a member flow. PKCE withS256 is mandatory.
Step 2 - Staff login and consent
The consent screen offers a Blackbird restaurant (back-of-house) sign-in. After the staff member signs in, the screen shows your app’s name and the requested scopes, and they approve or deny.- A diner signing in to a restaurant-scoped flow is a hard
403, not a downgrade. The two populations never cross. - If the staff member is already signed in to back-of-house in the same browser, that session is recognised and there is no second login. They see the consent prompt on first use and go straight through afterwards.
Steps 3 to 5 - Exchange, call, refresh
Identical to member OAuth. Exchange the code at/oauth/token from your
backend with client_secret and code_verifier. Keep the refresh token
server-side. Refresh tokens rotate on every use.
The token response carries the scopes you were granted:
Token claims
A restaurant-user access token carries the same claims as a member token, plus the principal discriminator.Identify the signed-in staff member
Your token’s only identity claim is a bare UUID. Call/restaurant_users/me to greet the person and learn where they work.
There is deliberately no
/restaurant_users/{id}. The only staff member
your app can ever name is the one who consented.
Routes a restaurant-user token unlocks
Sending a restaurant-user token to a member route (
/users/me/*) or an
app route (/events, /check_ins) is a 403 invalid_credential_type.
The credentials do not substitute for each other.
Authorization is two checks
A credential is not an authorization. Every restaurant route applies two independent checks, and both are needed.- Which credential. The route accepts only a restaurant-user JWT. An
API key or a diner token is rejected before the handler runs, with
403 invalid_credential_type. - Which location. The handler resolves the location the request
touches and checks it against the staff member’s current location
memberships. A location the person does not work at is
403 forbiddenwith the messageCannot access provided resource.
client_id. Your app never sees or edits another app’s events, even at
a shared location, and another app’s event id returns 404 before any
location check runs. Passes are not partitioned by app: a venue sees
every holder of a pass it is on, whichever app issued the holding.
Errors
All of these use the modern JSON envelope with
error.type,
error.code, and error.message, except the empty-body 401. See
Pagination + errors.
Listing your app in back-of-house
Back-of-house has an Apps section where staff can open your app already signed in, in one click. To appear there your app needs:- An initiate login URI: an absolute
httpsURL on your app, with no userinfo. It does not need to match a registered redirect URI. - At least one restaurant-user scope in its allowed scopes.
- A listing (tagline, description, category) approved by Blackbird. Contact Support to set the login URI and submit a listing.
SameSite=Lax cookie, and
redirects to /oauth/authorize. Because the staff member already has a
back-of-house session, the consent screen recognises it and they land on
your app with no second login.
Staff can disconnect your app from their connected apps in back-of-house.
That revokes every refresh chain for that person and your app, and
outstanding access tokens from those chains stop validating immediately.