Spoonjoy Developer Platform

A same-origin browser client does not fetch or store a bearer token. The chef signs into Spoonjoy with password, passkey, or any configured Google, GitHub, or Apple provider, and private API calls use the resulting session cookie. Those provider buttons are Spoonjoy sign-in methods, not OAuth providers that your client owns.

Login surface: /login
Then call: fetch("/api/v1/shopping-list", { credentials: "same-origin" })

For a script, device, or developer-owned client, the chef signs in first and runs POST /api/v1/tokens from Session auth, such as through the generated playground. An existing bearer credential with tokens:write can also create another token, but never with broader scopes than it already has. Spoonjoy returns the raw sj_... secret once; save it outside browser bundles.

POST /api/v1/tokens
Auth: Session cookie or Bearer sj_... with tokens:write
Body: { "name": "Kitchen script", "scopes": ["recipes:read", "cookbooks:read", "shopping_list:read", "shopping_list:write"] }
Response: { "ok": true, "data": { "token": "sj_...", "credential": { "id": "cred_...", "scopes": [...] } } }

For a third-party app, register a public client and redirect the chef to /oauth/authorize. If they are not signed in, Spoonjoy routes them through /login and the full auth surface before consent. The client never handles the chef's password. The client exchanges the authorization code at /oauth/token for an sj_... access_token plus rotating refresh_token.

POST /oauth/register -> client_id: cm_client_id_from_register
GET /oauth/authorize?client_id=cm_client_id_from_register&redirect_uri=...&response_type=code&scope=shopping_list%3Aread+shopping_list%3Awrite&state=...&code_challenge=...&code_challenge_method=S256
POST /oauth/token -> access_token: sj_...
POST /oauth/revoke -> revoke refresh_token and matching live OAuth access credentials

Spoonjoy's own native Apple app can exchange either a native Sign in with Apple credential or a Spoonjoy username/password credential for the app's rotating token session. This is a first-party app bootstrap path, not OAuth grant_type=password, and native clients must never persist the password after the request completes. The password endpoint is online-only, rate limited with Spoonjoy's dedicated auth limiter, returns no session cookie, and does not publish wildcard browser CORS headers.

POST /api/v1/auth/password/native
Content-Type: application/json
Body: { "emailOrUsername": "ari@spoonjoy.app", "password": "correct horse battery staple" }
Response: access_token sj_... + refresh_token ort_...

For clients that cannot run a browser-based OAuth callback, call POST /api/tools/start_agent_connection, show the authorizationUrl or stable verificationUri plus userCode to the chef, then poll POST /api/tools/poll_agent_connection no faster than the returned interval. Pass scopes for least privilege, such as shopping_list:read shopping_list:write; omitted scopes default to the same shopping-list read/write pair. The approval page also uses Spoonjoy's full login surface before issuing a one-time-display sj_... bearer token plus credential id. Personal and delegated bearer tokens do not expire unless expiresAt is non-null; rerun approval when a stored token returns 401 invalid_token. A device can revoke its own credential id with DELETE /api/v1/tokens/{credentialId}; revoking any other token requires tokens:write.

POST /api/tools/start_agent_connection -> verificationUri + verificationUriComplete + authorizationUrl + userCode + deviceCode + expiresIn: 600
POST /api/tools/poll_agent_connection -> status: pending | approved | denied | expired | claimed
Approved response -> token: sj_... + credential metadata, including scopes and expiresAt

Spoonjoy does not support an OAuth password grant or third-party API endpoint where a client trades a chef's password for a token. Browser email/password login creates a session cookie, not an API token. The only password-to-token exception is Spoonjoy's own native Apple app endpoint, which exists so the first-party app can sign in without shoving chefs through the website. Third-party clients should use OAuth/PKCE or delegated approval so Spoonjoy, not the client, handles password, passkey, and provider login.

Do not implement: grant_type=password
Use instead for third parties: OAuth/PKCE or delegated approval link

After a chef signs in, your logged-in Spoonjoy session is the credential. Call relative /api/v1 URLs with credentials: "same-origin". Do not send Authorization; if an Authorization header is present, bearer auth wins over the session.

await fetch("/api/v1/shopping-list", {
  credentials: "same-origin",
  headers: { "X-Request-Id": "web-shopping-list" },
});

Use bearer only when a client cannot share the logged-in Spoonjoy session. In the playground, leave auth on Session and run the generated POST /api/v1/tokens operation, then store the sj_... secret outside browser bundles. Bearer-created tokens inherit the caller's scopes by default. Bearer callers cannot create a token with broader scopes than they already have.

curl 'https://spoonjoy.app/api/v1/shopping-list' \
  -H 'Authorization: Bearer sj_client_token' \
  -H 'X-Request-Id: client-shopping-list'

Register a public client with token_endpoint_auth_method: none and no client secret, redirect the chef through consent, then exchange the single-use 60-second code with a form-encoded POST /oauth/token request. Registration accepts common RFC 7591/OIDC metadata, but Spoonjoy stores only client_name and exact redirect_uris today. Optional scope metadata can be validated at registration, but the authorize request scope is the grant. Use a 43-128 character high-entropy PKCE verifier, S256 code challenge, and state. If the chef is not signed in, Spoonjoy routes them through /login first, where password, passkey, and configured Google, GitHub, or Apple sign-in all return to consent. OAuth accepts account scopes, kitchen scopes, and least-privilege public, recipe, cookbook, and shopping-list scopes. Generic OAuth access tokens last 15 minutes (expires_in: 900). MCP-bound access tokens stay active until disconnect and omit expires_in. The refresh_token rotates on every refresh grant, and POST /oauth/revoke disconnects the stored refresh token plus live OAuth access credentials for that client/resource.

POST /oauth/register
Response: { "client_id": "cm_client_id_from_register" }
GET /oauth/authorize?client_id=cm_client_id_from_register&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&response_type=code&scope=shopping_list%3Aread+shopping_list%3Awrite&state=...&code_challenge=...&code_challenge_method=S256
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=...&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&code=...&code_verifier=...

POST /oauth/revoke
token=ort_...&client_id=cm_client_id_from_register&token_type_hint=refresh_token

Treat authentication_required and invalid_token as 401 responses, insufficient_scope as 403, and malformed Authorization headers as validation_error. Public endpoints can be anonymous; Omit `Authorization` on public calls unless you require authenticated behavior. If you send credentials to an optional endpoint, Spoonjoy validates them and checks scopes. Log requestId or X-Request-Id for support.

{
  "ok": false,
  "requestId": "client-shopping-list",
  "error": { "code": "insufficient_scope", "status": 403 }
}

Use for third-party apps that can receive a redirect callback and should never handle a chef password.

/.well-known/oauth-authorization-server -> /oauth/register -> /oauth/authorize -> /oauth/token -> /oauth/revoke

• - Dynamic client registration is public and returns token_endpoint_auth_method: none.
• - Redirect URIs must be HTTPS; HTTP is accepted only for localhost and 127.0.0.1.
• - PKCE is required: use a 43-128 character code_verifier and S256 code_challenge.
• - Authorization codes are single-use and expire after 60 seconds.
• - Access tokens are sj_... bearer credentials with a 900-second lifetime.
• - Refresh tokens are ort_... values and rotate on every refresh grant; POST /oauth/revoke disconnects a stored refresh token and revokes live OAuth access credentials for that client/resource.
• - Registration validates optional scope metadata but does not grant it; the authorize request scope is the grant. Blank authorize scope defaults to kitchen:read, but apps should send explicit least-privilege scopes.
• - Account profile, profile-photo, and notification settings require explicit account:read or account:write; broad kitchen scopes do not include account identity settings.
• - OAuth scopes never grant tokens:read or tokens:write; personal token management uses /api/v1/tokens.
• - grant_type=password is never supported.
• - Most OAuth errors use standard OAuth JSON. Rate-limit responses are Spoonjoy's generic rate-limit shape with Retry-After.

curl -sS 'https://spoonjoy.app/oauth/register' \
  -H 'Content-Type: application/json' \
  --data '{"client_name":"Example grocery app","redirect_uris":["https://example.com/oauth/callback"],"token_endpoint_auth_method":"none"}'

# Open this URL in the browser after generating a PKCE S256 challenge.
open 'https://spoonjoy.app/oauth/authorize?client_id=cm_client_id_from_register&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&response_type=code&scope=shopping_list%3Aread+shopping_list%3Awrite&state=...&code_challenge=...&code_challenge_method=S256'

curl -sS 'https://spoonjoy.app/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&client_id=cm_client_id_from_register&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&code=oac_...&code_verifier=pkce_verifier_0123456789_abcdefghijklmnopqrstuvwxyz_ABCDEF'

curl -sS -X POST 'https://spoonjoy.app/oauth/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'token=ort_...&client_id=cm_client_id_from_register&token_type_hint=refresh_token'

Use for agents, CLIs, kitchen displays, and constrained devices that can show a chef an approval URL but cannot run an OAuth callback.

/api/tools/start_agent_connection -> /api/tools/poll_agent_connection -> /api/v1/tokens/{credentialId}

• - The device code expires after 10 minutes.
• - Poll no faster than the returned interval, currently 2 seconds.
• - A pending poll returns pending plus authorizationUrl, verificationUri, verificationUriComplete, and userCode.
• - Pass scopes such as shopping_list:read shopping_list:write to request a least-privilege delegated token; omitted scopes default to shopping_list:read shopping_list:write.
• - Tiny devices can show verificationUri plus userCode instead of the long authorizationUrl.
• - An approved poll returns the sj_... token once, plus token metadata.
• - The token is a normal bearer credential. A device can revoke its own credential id with DELETE /api/v1/tokens/{credentialId}; revoking any other credential requires tokens:write.

SJ_BASE='https://spoonjoy.app'
umask 077
state_dir="$(mktemp -d "${TMPDIR:-/tmp}/spoonjoy.XXXXXX")"
trap 'rm -rf "$state_dir"' EXIT

curl -sS 'https://spoonjoy.app/api/tools/start_agent_connection' \
  -H 'Content-Type: application/json' \
  --data '{"agentName":"Kitchen display","scopes":"shopping_list:read shopping_list:write"}' \
  > "$state_dir/start.json"

echo "Open $(jq -r '.data.verificationUri' "$state_dir/start.json") and enter $(jq -r '.data.userCode' "$state_dir/start.json")"

while :; do
  curl -sS "$SJ_BASE/api/tools/poll_agent_connection" \
    -H 'Content-Type: application/json' \
    --data "{\"deviceCode\":\"$(jq -r '.data.deviceCode' "$state_dir/start.json")\"}" \
    > "$state_dir/poll.json"
  status=$(jq -r '.data.status' "$state_dir/poll.json")
  test "$status" = approved && break
  test "$status" = pending || exit 1
  sleep "$(jq -r '.data.interval // 2' "$state_dir/start.json")"
done
export SPOONJOY_TOKEN="$(jq -r '.data.token' "$state_dir/poll.json")"

Use for MCP-capable clients that discover OAuth metadata, get a bearer token, then call the remote Spoonjoy MCP endpoint.

/mcp -> /.well-known/oauth-protected-resource/mcp -> /.well-known/oauth-protected-resource -> /.well-known/oauth-authorization-server

• - POST /mcp challenges unauthenticated callers with path-specific OAuth protected-resource metadata.
• - MCP delegated scopes use kitchen:read and kitchen:write.
• - Token-management tools require personal tokens:read or tokens:write scopes; OAuth kitchen scopes do not grant them.
• - The approved bearer token must be sent as Authorization: Bearer sj_...

curl -sS 'https://spoonjoy.app/mcp' \
  -H 'Authorization: Bearer sj_...' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Register once per app install or environment, persist client_id, and do not register on every launch. Use HTTPS universal links or Android App Links for production callbacks, with localhost or 127.0.0.1 loopback only for development. Store tokens in Keychain or Android Keystore-backed storage. Refresh tokens rotate, so replace the stored refresh token atomically and use single-flight refresh when concurrent requests hit 401.

POST /oauth/register
{ "client_name": "Spoonjoy Apple", "redirect_uris": ["https://spoonjoy.app/oauth/callback"], "token_endpoint_auth_method": "none" }

GET /oauth/authorize?...&state=client_state&code_challenge=pkce_s256&scope=shopping_list:read+shopping_list:write

POST /oauth/token
grant_type=authorization_code&client_id=cm_client_id_from_register&redirect_uri=https%3A%2F%2Fspoonjoy.app%2Foauth%2Fcallback&code=oac_...&code_verifier=pkce_verifier_...

POST /oauth/token
grant_type=refresh_token&client_id=cm_client_id_from_register&refresh_token=ort_...

GET /api/v1/shopping-list/sync?limit=50

Use /api/v1/recipes/import with kitchen:write for full recipe clipping, or keep shopping_list:read shopping_list:write when the extension only syncs ingredient rows. Run OAuth/PKCE in the extension background, persist client_id plus state and code_verifier until callback, verify state, and make bearer API calls from the background instead of a content script. Register the HTTPS callback from chrome.identity.getRedirectURL/launchWebAuthFlow exactly; custom extension schemes are rejected.

POST /api/v1/recipes/import
Authorization: Bearer sj_...
{ "clientMutationId": "extension:recipe-import:...", "source": { "type": "url", "url": "https://example.com/recipe" } }

const item = { sourceRowId: "row-42", name: "Eggs", quantity: 12, unit: "Each" }
clientMutationId = `extension:${sha256(recipeUrl)}:${item.sourceRowId}:${bodyHash}`
POST /api/v1/shopping-list/items
Authorization: Bearer sj_...
{ "clientMutationId": "extension:...", "name": "Eggs", "quantity": 12, "unit": "Each" }

Omit cursor on the first sync, then store data.nextCursor after applying every item and tombstone. Use limit for small payloads and keep fetching while hasMore is true. Import with deterministic chef-wide mutation ids such as shopping-import:<source-system>:<source-row-id>:<body-hash>; this is not a durable set-desired-state API after the 24-hour idempotency window.

umask 077
tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/spoonjoy-sync.XXXXXX")"
trap 'rm -rf "$tmp_dir"' EXIT
curl -fsS 'https://spoonjoy.app/api/v1/shopping-list/sync?limit=20' \
  -H 'Authorization: Bearer sj_...' > "$tmp_dir/sync.json"
jq -n --arg cursor "$(jq -r '.data.nextCursor' "$tmp_dir/sync.json")" '{cursor:$cursor}' > state.json

Store access_token, rotating refresh_token, and cursor state behind a Durable Object, queue-level serializer, or D1 row lock. KV is fine for read-through snapshots after the lock, but not as the refresh-token compare-and-set mechanism. Respect Retry-After and never store authenticated bearer responses in caches.default.

Queue message: { chefId, mutation, clientMutationId }
Durable Object per chef: refresh once, atomically store the rotated refresh_token, then retry queued mutations with the same clientMutationId.
GET /api/v1/shopping-list/sync?limit=50
Authorization: Bearer sj_...

Import /api/v1/openapi.connector.json for an OpenAPI 3.0 REST-only profile. Configure OAuth as public client, no client secret, PKCE S256, authorization URL /oauth/authorize, token and refresh URL /oauth/token, revoke URL /oauth/revoke. API v1 has no webhooks yet; expose shopping-list sync as a polling trigger.

Trigger: New, updated, or removed shopping-list item
1. GET /api/v1/shopping-list/sync?limit=50
2. Sort returned rows by updatedAt descending for the no-code platform.
3. Dedupe events by id:updatedAt so changed items are not suppressed.
4. Treat deletedAt rows as removals or filtered tombstones.
5. Persist nextCursor only after the run succeeds.

Public recipe/cookbook lists use createdAt/id cursor walks. They are not repeatable snapshot guarantees or updatedAt incremental exports, and they do not include deletion tombstones; restart a full crawl when you need to catch public edits or removals. Preserve attribution, respect Retry-After, and do not treat public JSON as a photo-copying or commercial republication license.

snapshot_resource recipes recipes recipes.ndjson
snapshot_resource cookbooks cookbooks cookbooks.ndjson

GET /api/v1/recipes?limit=50
GET /api/v1/cookbooks?limit=50
GET /api/v1/recipes?cursor=v1.cursor_from_nextCursor&limit=50

Anonymous public responses may include Cache-Control: public, max-age=60, stale-while-revalidate=300 but not ETag or Last-Modified.

Fetch public JSON and render your own HTML with textContent, not innerHTML. Spoonjoy pages are not iframe embeds. Recipe steps are returned in ascending stepNum order, step duration is minutes when present, ingredients are step-attached in API order, and usingSteps lists prior step outputs used by a step. Validate sourceUrl as http/https before linking, write your own image alt text, and avoid copying photos where removals cannot be honored.

GET /api/v1/recipes/{id}
If 404 not_found, hide or replace the embed before rendering stale content.
Render servings, step ingredients, ordered steps, step output dependencies, and attribution.creditText as a link to attribution.canonicalUrl.
If attribution.sourceRecipe.deleted is true, credit it as unavailable instead of linking it.