# Authentication

This is the page to read carefully. Every Spoonity service authenticates
differently, and the differences are exactly the kind that produce a working
`curl` command that mysteriously 401s when you paste the same shape of
request against a different service. Verify the header name and the scope
vocabulary for the specific service you're calling — don't carry an
assumption over from the last one.

## Not on this page: how your *customers* sign in

This page is about how **you** — an integrator, a backend, an operator —
prove who you are to a Spoonity API. It is not about how a restaurant brand's
**end customers** sign in to that brand's app.

That is a separate service with its own page: [Auth](/docs/auth)
(`auth.spoonity.com`) — one-time codes over SMS, WhatsApp and email, magic
links, passkeys, Sign in with Apple and Google, and out-of-band approval for
POS terminals. It issues short-lived JWTs for a customer, not an API key for
you, and nothing in the table below applies to it.

Rule of thumb: if the credential belongs to someone who eats at the
restaurant, you want [Auth](/docs/auth). If it belongs to someone who builds
or operates the software, you are on the right page.

## Quick reference

| Service | Who this is for | Header | Credential shape | What gates access |
|---|---|---|---|---|
| **Auth** (consumer) | A brand's end customers, via its app/web/POS — **see [Auth](/docs/auth)** | `Authorization: Bearer <access token>` + `X-Spoonity-Vendor` | Short-lived RS256 JWT issued by `auth.spoonity.com` | The customer's own session, its `acr` assurance level, and tenant policy |
| CMS | Integrators, server-to-server | `X-API-Key: <key>` (static key) **or** `Authorization: Bearer <JWT>` (dashboard session) | `sck_` + 64 hex chars | `resource:verb` scopes (+ optional workflow role) |
| Links | Integrators, server-to-server | `X-API-Key: <key>` (static key) **or** `Authorization: Bearer <JWT>` (dashboard session) | `slk_` + 64 hex chars (Spoonity's own `slp_` platform keys also use `X-API-Key`; see [Links](#links)) | `resource:verb` scopes |
| Wallet | Integrator backends (never a browser) | `Authorization: Bearer <key>` (also accepted as `X-API-Key`, see below) | `sk_live_` + 43 base64url chars | Nothing — a key is scoped to one **program**, not a permission |
| Offers | Integrator backends, kiosks, ordering apps | `X-API-Key: <key>` **or** `Authorization: Bearer <key>` (header only in production) | Vendor API key issued by Spoonity | Nothing: a key has no role and reaches every `/v1/*` route for its vendor |
| Offers POS (`/partners/pos/*`) | A POS terminal or its middleware | `X-Spoonity-POS-Key: <key>` | One key per merchant, issued by Spoonity | Nothing beyond the vendor the key belongs to |
| Flags (SDK API) | Your apps (client key) and backends (server key) | `Authorization: Bearer <key>` | `sdk_c_` or `sdk_s_` + 26 lower-case Crockford base32 chars | Key kind (client or server); a key belongs to one environment of one brand |
| Flags (admin API) | People managing flags, and scripts they run | `Authorization: Bearer <session token>` | HS256 JWT from `POST https://flags.spoonity.com/auth/v1/login`, Spoonity account email and password | The person's role at the session's vendor (`admin` / `editor` / `viewer`) |
| Prism's own `/api/*` | Nobody outside Prism's own web app | HttpOnly session cookie (`prism_session`) | n/a — never an API key | Operator role (`admin` / `editor` / `viewer`) from the session, plus a second factor where the vendor requires one |
| Service-to-service (internal) | Trusted Spoonity services only, e.g. Prism's BFF | `Authorization: Bearer <Google-signed OIDC ID token>` + `X-Spoonity-Vendor` | Google identity token | Full access by default; see "Service-to-service" below |

The header is not interchangeable between services. **CMS and Links will not
accept a static API key over `Authorization: Bearer`** — that header is
reserved there for a dashboard JWT or a Google OIDC token, and a static key
sent that way is simply never checked against the API-key table, so you get a
`401` that looks identical to "bad token." **Wallet's own integration guide
uses `Authorization: Bearer`** for its static keys, though its middleware
also accepts the same key via `X-API-Key` as a fallback — prefer
`Authorization: Bearer` for Wallet since that's what every official example
shows.

## CMS

CMS layers three ways to authenticate on top of each other. `requireAuth`
looks at `Authorization: Bearer` first and reads `X-API-Key` only when no
Bearer header is present:

1. **`Authorization: Bearer <JWT>`** — a dashboard session, minted at
   CMS login. Full access to everything the operator's role permits; no
   `scopes` array, so every scope check passes.
2. **`X-API-Key: <key>`**, read only when there is no Bearer header: a
   static key. Two kinds share this header:
   - A **scoped key** (`sck_…`), created under a specific vendor with an
     explicit `scopes` array (see below). This is what you should mint for
     a new integration.
   - The **legacy vendor-wide key** — one per vendor, no scopes, full
     access (`scopes: ['*']`, role `admin`). Still live, still accepted,
     not what you should mint today.
3. **`Authorization: Bearer <Google OIDC ID token>`** — service-to-service,
   covered separately below. Tried only when the Bearer value doesn't
   verify as a CMS-signed JWT, and only when `TRUSTED_SERVICE_ACCOUNTS` is
   non-empty.

### Scopes

A scoped CMS key carries an array of `resource:verb` scopes:

`content:read` · `content:write` · `media:read` · `media:write` ·
`analytics:read` · `experiments:read` · `experiments:write` ·
`webhooks:read` · `webhooks:write` · `vendor:read` · `vendor:write` · `*`

Most routes are gated by `requireScope('<resource>')` (a few, such as
`/activity`, `/search`, `/users` and `/auth/me`, have no scope gate, and
`/lookups` is gated on `spaces`, which no scoped key can carry), which derives the
required scope from the HTTP method automatically: `GET`/`HEAD` need
`<resource>:read`, everything else needs `<resource>:write`. A `:write`
scope silently satisfies a `:read` check on the same resource — a key with
only `content:write` can also read content, so you don't need to list both.
`*` grants everything.

A CMS key can **also** carry an optional workflow `role` (`viewer` / `editor`
/ `admin`) alongside its scopes — this is separate from scope and drives the
content-approval workflow (draft → review → approve → publish); only an
admin dashboard session can mint a key that carries one, and a roleless key
can draft content (create/update spaces, blocks, translations,
personalization rules — anything gated by scope alone) but is rejected by
every route that requires a role, which is more than just the "obvious"
publish-side actions: **submit** already requires admin or editor (a
roleless key cannot even move a space into review), and approve, reject,
schedule, publish, unpublish, version-restore, and team-member management
all require admin outright, as does deleting a space, block or media asset.
See [CMS](/docs/cms#authentication) for the
exact role requirement per endpoint.

### Example

```bash
curl https://cms.spoonity.com/api/v1/spaces \
  -H "X-API-Key: sck_REPLACE_WITH_YOUR_KEY"
```

### Dashboard login email allowlist

`POST /auth/login` and `POST /auth/select-vendor` (see [CMS](/docs/cms#post-authlogin)) restrict
which email domains may sign in at all, gated by `ALLOWED_EMAIL_DOMAINS` (comma-separated; `*`
disables the restriction). It is checked at login and again on every request that carries a
dashboard JWT, so an existing session for a domain removed from the list gets `403` on its next call.
API keys and service tokens are not checked against it. By default
the allowlist covers Spoonity staff plus one additional partner domain that manages its own CMS
content directly; a deployment overrides the whole list via `ALLOWED_EMAIL_DOMAINS`. A domain
outside the allowlist gets a flat `403 forbidden`, with a message that no longer names Spoonity by
name.

## Links

Links follows the identical mechanism to CMS — same three-tier
`requireAuth`, same `X-API-Key` vs. `Authorization: Bearer` split, same
`requireScope('<resource>')` deriving `:read`/`:write` from the HTTP method,
same `:write`-implies-`:read` rule. What differs is the **resource
vocabulary** — Links has no `content` or `media`, and has three resources
CMS doesn't:

`links:read` · `links:write` · `analytics:read` · `webhooks:read` ·
`webhooks:write` · `bio:read` · `bio:write` · `deeplinks:read` ·
`deeplinks:write` · `vendor:read` · `vendor:write` · `*`

(Note `analytics` has no `:write` variant in either service — it's
inherently read-only.)

Links also has a legacy vendor-wide key (`X-API-Key`, `scopes: ['*']`,
full access), same shape as CMS's.

Links has one mode CMS does not: a **platform key** (`slp_…`), sent as
`X-API-Key`, for Spoonity's own services. It is a service identity rather
than a vendor key: it carries no scopes and names the tenant per call with
`X-Spoonity-Vendor` (and optionally `X-Spoonity-Vendor-Name`), like the
OIDC path below. It is not issued to integrators.

Prism's own key-creation UI presents these as six checkable "areas" (Links,
Analytics, Webhooks, Link in Bio, Deep Links, Vendor Settings) rather than
as literal scope strings — that's a UI simplification, not a different wire
format. Ticking "Links" and creating the key still produces
`["links:read", "links:write"]` (or just `["links:read"]` for a
read-only grant) under the hood, and `requireScope` on the Links side
resolves it exactly like CMS resolves its own scope strings.

### Example

```bash
curl https://links.spoonity.com/api/v1/links \
  -H "X-API-Key: slk_REPLACE_WITH_YOUR_KEY"
```

## Wallet

Wallet is the outlier: a key is **not** scoped by permission at all — it's
scoped to exactly one **loyalty program** (`programId`). There is no
`content:read`-style vocabulary to learn. A request either presents a key
that belongs to the program named in the request body, or it's rejected —
`programId does not match this API key's scope.` is the actual 403 for a
key used against the wrong program.

Keys are minted per program from Prism (`/settings/api-keys` → Wallet
panel → pick a program → create). The raw key — prefixed `sk_live_` — is
shown exactly once at creation, same as every other service here.

### The enrollment endpoint

```
POST https://wallet-api.spoonity.com/v1/enroll/session
```

- **Auth:** `Authorization: Bearer sk_live_YOUR_API_KEY`
- **Body:**
  ```json
  {
    "programId": "YOUR_PROGRAM_ID",
    "user": { "name": "Jane Doe", "email": "jane@example.com", "externalId": "user_123" },
    "consentGiven": true
  }
  ```
- **Response:**
  ```json
  { "sessionUrl": "https://pass.spnty.co/enroll/s/<opaque_key>",
    "expiresAt": "2026-07-15T13:15:00.000Z",
    "alreadyEnrolled": false }
  ```
- **Errors:** `400` (missing/invalid field), `401` (bad or revoked key),
  `403` (`programId` doesn't match this key), `429` (rate limited — see
  [Conventions](/docs/conventions)), `500`.

Redirect the customer's browser to `sessionUrl`; it is a short-lived (15
minute), one-time link, not something you call from a backend a second time.

A separate, **unauthenticated** variant exists for calling directly from a
mobile app that already holds the customer's own live Spoonity session —
`POST /enroll/app-session` with `{ programId, spoonitySessionKey,
consentGiven }` and no API key at all, since the customer's own session key
is the credential. Full endpoint reference: [Wallet](/docs/wallet).

### Example

```bash
curl -X POST https://wallet-api.spoonity.com/v1/enroll/session \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "YOUR_PROGRAM_ID",
    "user": { "name": "Jane Doe", "email": "jane@example.com", "externalId": "your_user_id_123" },
    "consentGiven": true
  }'
```

## Offers

Offers ([Offers](/docs/offers), `offers.spoonity.com`) takes a different
credential on each of its two integration surfaces.

**`/v1/*` (evaluate, lifecycle, admin catalog):** a vendor API key, in
either header:

```bash
curl https://offers.spoonity.com/v1/offers \
  -H "X-API-Key: YOUR_OFFERS_API_KEY"
```

`Authorization: Bearer YOUR_OFFERS_API_KEY` works the same way; `X-API-Key`
is checked first. Unlike CMS and Links, Offers does accept a static key over
`Authorization: Bearer`. The key must be in a header: in production a
request carrying `?api_key=` is refused with `401 UNAUTHORIZED` even when the
key is right. There are no scopes and no role on a key, so it can call every
`/v1/*` route for its vendor, admin writes included. Keys are issued by
Spoonity; Prism has no Offers panel under `/settings/api-keys`.

**`/partners/pos/*` (POS check):** `X-Spoonity-POS-Key: YOUR_POS_KEY`. One
key per merchant, and the key alone decides the merchant. The `/v1`
credentials are not accepted here, and a POS key is not accepted on `/v1`.

**Trusted services:** Prism's BFF reaches Offers' admin routes with a
Google OIDC token plus `X-Spoonity-Vendor`, `X-Spoonity-User` and
`X-Spoonity-Role`; see the service-to-service section below.

## Flags

Flags has two credentials, one per API surface, both sent as
`Authorization: Bearer`. It has no `X-API-Key` header at all. Full reference:
[Flags](/docs/flags#authentication).

### SDK keys (`/sdk/v1`)

| Kind | Prefix | Secrecy | May call |
|---|---|---|---|
| client | `sdk_c_` | Public: it ships inside the app | `definitions`, `memberships`, `impressions`, `events`, `stream` |
| server | `sdk_s_` | Secret: backend only | everything a client key may, plus `segments/{name}`, `flags/{flag}` and `evaluate` |

There are no scopes. A key is bound to one **environment** (for example
`production` or `staging`) of one brand, and that alone decides what it can
read; there is no vendor header. A client key on a server-only route answers
`403`, and an unknown or revoked key `401`. The service keeps only a SHA-256
hash; the plaintext is shown once, when the key is created.

Keys are created by a brand **admin**, in Prism at ⚙ Product settings →
**SDK keys**, in the Flags console at `https://flags.spoonity.com/`, or through
`POST /admin/v1/environments/{env}/keys`. Unlike CMS and Links scoped keys,
the whole lifecycle (list, create, revoke) works from Prism.

```bash
curl -X POST https://flags.spoonity.com/sdk/v1/evaluate \
  -H "Authorization: Bearer sdk_s_REPLACE_WITH_YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "member:10442817", "flags": ["checkout-redesign"], "dryRun": true }'
```

### Admin sessions (`/admin/v1`)

The admin API takes a session token for a person's Spoonity platform account:
`POST https://flags.spoonity.com/auth/v1/login` with `{ email, password }`
returns `token` (valid 24 hours by default), or a `selection_token` to
exchange at `/auth/v1/select-vendor` when the account has several vendors.
Bodies match the CMS's `/api/v1/auth/*`. The token is bound to one vendor:
every admin route is confined to that brand's workspace, and another brand's
answers `404`. The role follows the person's platform role at that vendor
(owner or administrator → `admin`; manager, editor or staff → `editor`;
anything else → `viewer`).

There is no API key for the admin API. A script that manages flags signs in
as a person with the right role.

### Service identity

Flags also accepts Google ID tokens on `/admin/v1`, for Spoonity staff and
for Spoonity's own service accounts. Prism's BFF uses this path and names the
operator it acts for in `X-Spoonity-Vendor`, `X-Spoonity-User` and
`X-Spoonity-Role`; Flags then confines the call to that vendor's workspace,
records the operator as the actor, and caps the role at the service account's
own. The headers are ignored from any caller that is not an allow-listed
Spoonity service account. Not available to integrators.

## Prism's own `/api/*`

**Not an integration surface.** Everything under `https://prism.spoonity.com/api/*`
is authenticated by a single HttpOnly, Secure, SameSite=Lax session cookie
(`prism_session`) set at `POST /auth/login`, and by nothing else — there is
no API-key path into Prism's own API, and there never has been one. The
cookie carries the operator's email, active vendor, role, and `amr` (how the
session was authenticated), and is checked against a server-side session
record on every request through a 30-second cache (so a logged-out cookie
stops working within about 30 seconds, not just at its 24h expiry). If you're
looking at Prism's network tab and thinking about calling one of these
routes yourself: don't — they exist to serve Prism's own UI, they can change
shape without notice, and no credential you can obtain as an integrator will
satisfy them. If you want programmatic access to CMS, Links, Wallet or
Insights, call that service directly using the mechanisms above, not Prism's
proxy.

### The second factor

Sign-in is a handshake, not a single call, and since 2026-09 it can have a
second step. `POST /auth/login` (or `POST /auth/select-vendor`, for an
operator with several vendors) answers one of:

- `{status:'ok', …}` — signed in, cookie set. What every operator who has not
  enrolled a factor, at a vendor with no policy, still gets.
- `{status:'requires_mfa', mfa_token, methods, …}` — the operator has a
  factor and must clear it at `/auth/mfa/verify/*` or `/auth/mfa/passkey/*`.
- `{status:'requires_mfa_enrollment', mfa_token, …}` — the vendor's policy
  requires a second factor and this operator has none yet; they set one up at
  `/auth/mfa/enroll/*`, which completes the sign-in.

Five factors are supported — authenticator app (TOTP), passkey/security key
(WebAuthn), an emailed code that doubles as a single-use magic link, an SMS
code, and ten single-use recovery codes — plus an optional "remember this
browser for 30 days" cookie. Which of them an operator may use is decided
server-side from their enrollment and the active vendor's policy; the client
is told, never asked.

The session that results carries an `amr` claim listing the methods that were
cleared (`pwd`, `totp`, `passkey`, `sms`, `email`, `recovery`,
`trusted_device`), reported to the SPA as `user.mfa: {verified, methods}` on
every `/auth/me`, login and vendor switch. `POST /auth/switch-vendor` into a
vendor whose policy requires a second factor, from a session whose `amr` has
none, answers `403 {code:'mfa_required'}` — the client signs out and the next
sign-in gates properly.

None of this changes the integration surface: `/auth/mfa/*` is as internal as
the rest of `/auth`, there is still no API-key path into Prism, and nothing
an integrator can obtain will satisfy any of it. Operators manage their own
factors at `/settings/security`; the ops side (secrets, TTLs, enabling the
SMS and email gateways, break-glass) is `docs/ops/mfa.md`. SMS and email
share one AWS credential secret (`prism-aws-credentials`), which currently
ships empty, so `GET /auth/mfa/me` reports
`capabilities.sms` and `capabilities.email` as `false` and neither channel is
offered until an admin adds a credential.

## Service-to-service (internal — not callable by integrators)

CMS, Links, Wallet and Offers all accept a **Google-signed OIDC identity token** as
a fourth way in, used only by trusted Spoonity infrastructure (Prism's BFF,
CMS's MCP server, and similar) — never by an external integrator, since it
requires a Google Cloud service-account identity these services' own
`TRUSTED_SERVICE_ACCOUNTS` allowlists name explicitly.

The shape, common to CMS and Links: `Authorization: Bearer <id_token>` with
an audience the target service recognizes, plus a required
`X-Spoonity-Vendor: <spoonity_vendor_id>` header naming the tenant for that
call (vendors are auto-provisioned on first use). A caller authenticated
this way gets full access — no `scopes` array at all, treated the same as a
dashboard session for scope checks. In CMS it is gated instead by a role
(`SERVICE_AUTH_ROLE`, default `editor`: can create/edit/submit content but
not approve, publish, or delete). Links has no service role, so a trusted
service caller there has full access, deletes included; only the
dashboard-session-only credential routes refuse it.

One caller, Prism's BFF, is additionally allow-listed by CMS (not by Links —
see the limitation below) to **forward** a specific human operator's
identity rather than acting as itself: it adds `X-Spoonity-User: <email>`
and `X-Spoonity-Role: <admin|editor|viewer>`, and CMS substitutes that role
for `SERVICE_AUTH_ROLE`. Both headers are required together for an
allow-listed forwarding caller — a missing or unrecognized role is a hard
`401`, never a silent default — and are read at all only for a caller on
that specific allowlist; sending them yourself, from anywhere else, does
nothing.

Offers accepts the same mechanism on `/v1/*`, with the three headers read
for every trusted caller rather than for one forwarding allowlist:
`X-Spoonity-Vendor` is required (`^[A-Za-z0-9_-]{1,64}$`, missing or
malformed is `401`), `X-Spoonity-User` is optional and stamped on
`created_by` / `updated_by`, and `X-Spoonity-Role` must be exactly `admin`,
`editor` or `viewer`. There is no configured default role: an absent or
unrecognized role is treated as `viewer`, which gets `403 FORBIDDEN` on
every write under `/v1/admin/*` except the side-effect-free simulator. The
vendor API key is still tried first, so kiosks are unaffected.

Wallet accepts the same Google-OIDC mechanism through its own `requireAuth`,
as a peer to its operator-session cookie rather than a separately-gated
path — which is *why* Wallet's key management works through Prism with no
special case (see below), unlike CMS's and Links's.

## Creating and rotating keys

Key management for CMS, Links and Wallet happens **in Prism**, at
`/settings/api-keys`; Offers keys are issued by Spoonity (see the table). Wallet keys can also still be managed from Pass Studio
(`studio.spoonity.com`) on its Integrations tab. What actually works in Prism differs by service today, and
this is worth knowing before you go looking for a "Create key" button that
turns out to be missing:

| Service | Action | Works via Prism? |
|---|---|---|
| Wallet | Create / list / revoke a per-program key | **Yes** — full lifecycle |
| CMS | View / rotate the **legacy** vendor-wide key | **No** — `POST /vendor/api-key/rotate` requires a CMS dashboard session (`requireJwtSession`); Prism's service identity is refused by name, `403 "This action requires a dashboard session"` |
| CMS | View the legacy key's status (whether one exists) | **Yes** — `GET /vendor/api-key/status` only requires the `vendor` scope, which Prism's service session has |
| CMS | Create / list / revoke a **scoped** key | **No** — same `requireJwtSession` gate, on the whole `/vendor/api-keys` router |
| Links | View / rotate the legacy vendor-wide key | **Yes** — Links, unlike CMS, does not gate `POST /vendor/api-key/rotate` behind a dashboard session; it only requires the `vendor` scope |
| Links | Create / list / revoke a **scoped** key | **No** — same `requireJwtSession` gate as CMS, on the whole `/vendor/api-keys` router |
| Offers | Create / list / revoke a vendor API key or POS key | **No**. Offers has no key-management API; keys are issued by Spoonity |
| Flags | Create / list / revoke an SDK key | **Yes**, for a Prism admin at the brand, at ⚙ Product settings → **SDK keys** (not under `/settings/api-keys`) |

For the two "No" rows on each service, Prism shows a plain "Not yet
available in Prism" notice and withholds the Create button, rather than a
raw failed-to-load error — that's a deliberate degrade, not a bug, and it's
the same root cause both times: `requireJwtSession` in CMS's and Links's own
middleware refuses any `authMethod` other than `jwt` by name, and Prism's
BFF authenticates to them as a service identity (`authMethod: 'service'`),
never as a dashboard JWT — by design, since minting one would mean Prism's
BFF forging a first-party CMS/Links login for the operator. **The only way
to create or revoke a scoped CMS or Links key today is to sign in to that
service's own dashboard directly** (`cms.spoonity.com` /
`links.spoonity.com`) and use its native API-keys page.

Wallet has no such gate at all — its `requireAuth` treats an operator
session and a Prism service token as peers, so every Wallet key operation
that works from Wallet's own UI also works from Prism's.

This is a real, current limitation, not a documentation gap — track it
upstream via `docs/audit/cms-scoped-keys-403.md` in this repo, which has the
full root-cause writeup and a sketch of the upstream fix, if you need to
reference it.

## See also

- [Conventions](/docs/conventions) — error envelopes, rate limits, and the
  other cross-cutting rules referenced above
- [CMS](/docs/cms) · [Links](/docs/links) · [Wallet](/docs/wallet) ·
  [Insights](/docs/insights) · [Offers](/docs/offers) · [Flags](/docs/flags) · [Prism](/docs/prism)
