Skip to main content
Flynet has a third principal beside the app (API key) and the member (OAuth bearer): the restaurant user. A restaurant user is one member of a restaurant’s staff who signs in with their Blackbird back-of-house account and consents to your app. The token you get back lets your app act for that person at the locations they work at. The wire mechanics are the same OAuth 2.0 + PKCE flow described in OAuth. What changes is who signs in at the consent screen, which scopes you ask for, and which routes the token opens.
From the kitchen - Reach for restaurant auth when a restaurant is your customer: an events tool a manager uses, a pass programme a venue opts in to, a staff-facing dashboard. If you are reading Blackbird-managed data about a location (its specials, challenges, hours), you want an API key. If you are acting for a diner, you want member OAuth.

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 sub is the staff member’s restaurant user id. A principal_type: RESTAURANT_USER claim 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.
Holding the token proves the caller is staff somewhere. It never proves they are staff here. Every route that touches a location checks that location against the person. See Authorization is two checks.

Scopes

Restaurant-user scopes carry a restaurant_ 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 with S256 is mandatory.
Blackbird validates the client, the redirect URI (exact match), and the scopes, records on the flow that a restaurant user must sign in, and 302-redirects the browser to the consent screen. 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.
  1. 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.
  2. 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 forbidden with the message Cannot access provided resource.
Events add a third partition: every read and write is scoped to your 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.
Chef’s warning - Do not cache a staff member’s locations from /restaurant_users/me and treat them as an authorization. The API re-reads memberships on every request, so a cached list can be stale in both directions. Use it for display, and let the API decide.

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 https URL 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.
Back-of-house links staff to your initiate login URI. Your server mints PKCE, stores the verifier in an HttpOnly 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.
Chef’s warning - Never accept a token in a URL as a shortcut for this. Query strings land in browser history, Referer headers, and access logs, and nothing binds a pasted link to the person who opens it. The only credential that may appear in a URL is the single-use authorization code, which is useless without your client_secret and PKCE verifier.
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.

Lifetimes

Same as member tokens: access tokens last 60 minutes, refresh tokens up to 30 days and rotate on every use. See Credential lifetimes.