Spoonity API Documentation View as Markdown Prism console

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:

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

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:

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#