> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flynet.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Restaurant auth

> Act on behalf of restaurant staff. The restaurant-user OAuth flow, its scopes, and the venue routes it unlocks.

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](https://docs.flynet.org/concepts/oauth.md). What changes is who signs in at the consent
screen, which scopes you ask for, and which routes the token opens.

> [!TIP]
>
> **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](https://docs.flynet.org/concepts/api-keys.md). If you are acting for a diner, you want
> member [OAuth](https://docs.flynet.org/concepts/oauth.md).

## 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.

| Principal | Who is asking | Credential | Path shape | Scope key |
| - | - | - | - | - |
| **Public** | anyone | none | `/restaurants`, `/locations` | none |
| **App** | your app as itself | `X-API-Key` | bare resource: `/check_ins`, `/events`, `/tiers` | `read:<resource>` |
| **Member** | a diner who consented | `Authorization: Bearer` (user JWT) | `/users/me/<resource>` | `read:<resource>` or `read:user_<resource>` |
| **Restaurant user** | a staff member who consented | `Authorization: Bearer` (restaurant-user JWT) | `/restaurant_users/me`, `/venues/me/<resource>` | `read:restaurant_<resource>` |

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](#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.

| Scope | Gates | Self-service in Make |
| - | - | - |
| `read:restaurant_profile` | `GET /restaurant_users/me` | Yes |
| `read:restaurant_events` | `GET /restaurant_events` | Yes |
| `write:restaurant_events` | `POST /restaurant_events`, `PATCH /restaurant_events/{id}` | Yes |
| `read:restaurant_passes` | `GET /venues/me/passes`, `GET /passes/{id}/holders` | Yes |
| `write:restaurant_passes` | `POST /venues/me/passes/{id}/venues`, `DELETE /venues/me/passes/{id}/venues/{venueId}` | No, ask [Support](https://docs.flynet.org/resources/support.md) |

> [!NOTE]
>
> **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](https://docs.flynet.org/concepts/oauth.md). The differences are
marked.

```text theme={null}
1. Browser -> /oauth/authorize?scope=read:restaurant_profile ...   (restaurant scopes)
2. Staff member signs in with their back-of-house account, approves  (staff login, not diner)
3. Callback -> your backend -> /oauth/token                           (identical)
4. API calls with Authorization: Bearer <access_token>               (restaurant routes)
5. Refresh -> /oauth/token with grant_type=refresh_token             (identical)
```

### Step 1 - Authorize with restaurant scopes

All seven parameters are required, exactly as for a member flow. PKCE
with `S256` is mandatory.

```text theme={null}
GET https://api.staging.blackbird.xyz/oauth/authorize
  ?client_id=<your client_id>
  &redirect_uri=https://yourapp.com/oauth/callback
  &scope=read:restaurant_profile%20read:restaurant_events
  &state=<random>
  &code_challenge=<BASE64URL(SHA256(code_verifier))>
  &code_challenge_method=S256
  &response_type=code
```

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.

### 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:

```json theme={null}
{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh>",
  "scope": "read:restaurant_profile read:restaurant_events"
}
```

### Token claims

A restaurant-user access token carries the same claims as a member
token, plus the principal discriminator.

| Claim | Value |
| - | - |
| `sub` | Restaurant user UUID. Matches `id` from `/restaurant_users/me`. |
| `principal_type` | `RESTAURANT_USER` (a member token carries `USER`). |
| `client_id` | Your app's client id. Restaurant-authored resources are partitioned by it. |
| `scope` | Space-separated granted scopes. |
| `aud`, `iss`, `iat`, `exp`, `jti`, `chain_id` | As for member tokens. See [OAuth](https://docs.flynet.org/concepts/oauth.md#identify-the-authenticated-member). |

## 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.

```bash theme={null}
curl https://api.staging.blackbird.xyz/flynet/v1/restaurant_users/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json theme={null}
{
  "id": "7f3a2c81-5d2e-4b8a-9c1f-2e4d6a8b0c3e",
  "object": "restaurant_user",
  "email": "chef@example.com",
  "first_name": "Jamie",
  "last_name": "Rivera",
  "locations": [
    {
      "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "object": "location",
      "name": "Hayes Valley",
      "restaurant": { "id": "14339db3-2e7a-42c4-aa98-4c0fb18679eb", "object": "restaurant", "name": "Rich Table" },
      "neighborhood": { "id": "...", "object": "neighborhood", "name": "Hayes Valley", "region": "San Francisco" },
      "address": { "street": "199 Gough St", "city": "San Francisco", "state": "CA", "zipcode": "94102", "country": "US" },
      "time_zone": "America/Los_Angeles",
      "payments_enabled": true
    }
  ]
}
```

| Field | Notes |
| - | - |
| `first_name`, `last_name` | Both set or both `null`. Fall back to `email` when null. |
| `locations` | The same `location` object the location routes return. **May be empty**: a staff member whose grants were all removed still has a valid login. Render "no locations" rather than crashing on `locations[0]`. |

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

| Method and path | Scope | What it does |
| - | - | - |
| `GET /restaurant_users/me` | `read:restaurant_profile` | The consenting staff member and their locations. |
| `GET /restaurant_events?location_id=` | `read:restaurant_events` | Your app's events at one of the caller's locations. `location_id` is required. |
| `POST /restaurant_events` | `write:restaurant_events` | Create an event at a location the caller works at. |
| `PATCH /restaurant_events/{id}` | `write:restaurant_events` | Update one of your app's events. |
| `GET /venues/me/passes` | `read:restaurant_passes` | Every pass at least one of the caller's venues is on. |
| `GET /passes/{id}/holders?state=active` | `read:restaurant_passes` | Who holds a pass the caller's venue is on. Name and avatar only. |
| `POST /venues/me/passes/{id}/venues` | `write:restaurant_passes` | Opt one of the caller's venues in to a pass. |
| `DELETE /venues/me/passes/{id}/venues/{venueId}` | `write:restaurant_passes` | Opt a venue out. |

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.

> [!WARNING]
>
> **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

| Status and code | When | Fix |
| - | - | - |
| `/authorize` redirects with `error=invalid_scope` | Scope set mixes restaurant and diner scopes, includes an API-key scope, or asks for a scope your app does not hold. | Request only restaurant scopes your app is approved for. |
| `403` at the consent screen | A diner session tried to complete a restaurant-scoped flow. | Sign in with a back-of-house account. |
| `401` empty body, `WWW-Authenticate: Bearer` | Missing, malformed, or expired bearer. | Refresh, or restart the flow. |
| `400` `ambiguous_credentials` | Request carried both `X-API-Key` and `Authorization: Bearer`. | Send exactly one credential. |
| `403` `invalid_credential_type` | Right scope family, wrong credential: an API key or a diner token on a restaurant route, or a restaurant token on a member or app route. | Use the credential the route family expects. |
| `403` `insufficient_scope` | Restaurant-user token without the route's scope. The `WWW-Authenticate` header names the missing scope. | Re-authorize with the required scope. |
| `403` `forbidden`, `Cannot access provided resource.` | The staff member does not work at the location the request touches. | Pick a location from `/restaurant_users/me`, or have the restaurant grant the person access in back-of-house. |

All of these use the modern JSON envelope with `error.type`,
`error.code`, and `error.message`, except the empty-body `401`. See
[Pagination + errors](https://docs.flynet.org/concepts/pagination-errors.md).

## 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](https://docs.flynet.org/resources/support.md) 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.

> [!WARNING]
>
> **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](https://docs.flynet.org/concepts/authentication.md#credential-lifetimes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.