BAPI & SDK changelog

This page tracks changes to the Backend API (BAPI), Frontend API (FAPI) and the SDKs, with breaking changes called out. The machine-readable API shape is always at `GET /v1/openapi.json` (OpenAPI 3.1) — diff it between deploys to see exactly what changed.

Versioning policy

• The BAPI is snake_case with a stable { data, errors:[{code,message,field}] } envelope, idempotency keys on writes, and cursor pagination (starting_after / next_cursor).

• Additive changes (new fields, new endpoints, new optional inputs) ship continuously and are not breaking.

• A breaking change is announced here with a deprecation window; where a method or path changes, the old form returns an explanatory error rather than a silent 404.

• Pin nothing to undocumented behavior; if it's not in /v1/openapi.json, treat it as internal.

2026-09

• `GET /v1/openapi.json` now serves the full OpenAPI 3.1 spec (499 paths) — generate a client instead of hand-rolling calls.

• `offline_access` is advertised in discovery scopes_supported and accepted at client registration (refresh tokens were always issued; now it's requestable).

• `POST /v1/users`: accepts email_address as a string or a Clerk-style array; returns an actionable 422 on bad input (previously some inputs 500'd).

• User object now includes Clerk-shaped email_addresses + primary_email_address_id on GET /v1/users/:id, list, create and update.

• `POST /v1/user_imports`: accepts the Clerk aliases password_digest / password_hasher in addition to password_hash (argon2id + bcrypt imported verbatim).

• Session token carries the email claim by default (auth_config.session.includeEmailClaim), and the session cookie is parent-scoped for custom domains by default (crossSubdomainCookies).

• Provider tokens brokered via GET /v1/users/:id/oauth_access_tokens/:provider now include metadata (e.g. Salesforce instance_url, Stripe stripe_user_id).

• `GET /v1/diagnostics/login_readiness?origin=…` added — the end-to-end login-readiness probe.

⚠️ Breaking-change note

• The deploy/trigger-style endpoint changed GET → POST in an earlier release. If a call returns "this endpoint has changed to a POST request," switch the method. Future method/path changes will appear here with a deprecation window.