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
(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. 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 | 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) |
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:
Authorization: Bearer <JWT>— a dashboard session, minted at CMS login. Full access to everything the operator's role permits; noscopesarray, so every scope check passes.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 explicitscopesarray (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: ['*'], roleadmin). Still live, still accepted, not what you should mint today.
- A scoped key (
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 whenTRUSTED_SERVICE_ACCOUNTSis 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 for the
exact role requirement per endpoint.
Example#
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) 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#
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:
{ "programId": "YOUR_PROGRAM_ID", "user": { "name": "Jane Doe", "email": "jane@example.com", "externalId": "user_123" }, "consentGiven": true } - Response:
{ "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(programIddoesn't match this key),429(rate limited — see 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.
Example#
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, 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:
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.
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.
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.