Authentication

OAuth 2.0 authorization server metadata

Returns RFC 8414 authorization server metadata (also served at `/.well-known/openid-configuration`). Describes all OAuth 2.1 endpoints, supported grant types, PKCE methods, and dynamic client registration endpoint.

Auth

Responses

OAuth 2.0 protected resource metadata

Returns RFC 9728 protected-resource metadata for the MCP API surface. Lists the authorization server(s) and supported bearer methods.

Auth

Responses

OAuth 2.0 protected resource metadata (MCP path variant)

Alternative path for RFC 9728 protected-resource metadata targeting `/v1/mcp` specifically. Returns the same document as `/.well-known/oauth-protected-resource`.

Auth

Responses

OpenID Connect discovery document

Alias for `/.well-known/oauth-authorization-server`. Returns the same RFC 8414 authorization server metadata. Provided for compatibility with OpenID Connect clients.

Auth

Responses

OAuth 2.0 authorization endpoint

Initiates the OAuth 2.0 authorization code flow with PKCE (S256 required, plain rejected per RFC 7636 §4.6). Redirects the user to the consent page on success, or returns an RFC 6749 error response.

Auth

Parameters

Responses

Dynamic client registration (RFC 7591)

Registers a new OAuth 2.0 client dynamically per RFC 7591. Returns a `client_id` for use in subsequent authorization requests.

Auth

Request Body

Responses

OAuth 2.0 token endpoint

Exchanges an authorization code for an access token using the `authorization_code` grant type. The PKCE verifier must match the challenge submitted in `/oauth/authorize`. Accepts `application/x-www-form-urlencoded` or `application/json`. **Response format is RFC 6749 style** — not the standard Backbuild envelope.

Auth

Request Body

Responses

Complete email-verified registration

Completes a passwordless registration flow started by `/initiate`. Verifies the code, sets the password, creates the account, and returns session tokens. May return `mfa_enrollment_required` when the org mandates MFA before granting full access. Password must meet complexity requirements and must not appear in known breach databases. Requires a Cloudflare Turnstile token.

Auth

Request Body

Responses

Grant test entitlements (dev only)

Development-only endpoint that grants test plan entitlements to the authenticated user's organization. Returns `404 NOT_FOUND` in non-dev environments.

Auth Session JWT (Bearer)

Responses

Purge test organization (dev only)

Development-only endpoint that purges the test organization and optionally specific users. Returns `404 NOT_FOUND` in non-dev environments. The caller must be authenticated and the target org must be a test organization.

Auth Session JWT (Bearer)

Request Body

Responses

Initiate device authorization flow

Starts the OAuth 2.0 device authorization flow (RFC 8628 adapted with PKCE). The client provides a PKCE code challenge and receives a device code, user code, and verification URI. The user visits the verification URI in a browser to authorize the device. **Note**: This endpoint returns a raw JSON object, not the standard Backbuild envelope.

Auth

Request Body

Responses

Approve device authorization (browser user)

Called by the authenticated browser user to approve a pending device authorization. The user enters the `user_code` displayed on the device. On success, the authorization code is minted and the device can exchange it for tokens.

Auth Session JWT (Bearer)

Request Body

Responses

Exchange device authorization code for tokens

Exchanges the authorization code from the device flow for an access token (and optionally a refresh token). The PKCE verifier must match the challenge submitted in `/device/authorize`. Supports `token_type=jwt` for a full JWT session or `token_type=api_key` (default) for a long-lived opaque API key. **Response format is RFC 6749 style** (`{access_token, token_type, expires_in?, refresh_token?}`), not the standard Backbuild envelope.

Auth

Request Body

Responses

Authenticate with Google OAuth

Exchanges a Google authorization code for session tokens. Creates a new account if the email does not exist, or links/logs into an existing account. Returns `mfa_required`, `mfa_enrollment_required`, or `google_link_required` when further action is needed. An optional `mfaDeviceToken` (or array `mfaDeviceTokens` for multi-org) bypasses the MFA challenge for a remembered device.

Auth

Request Body

Responses

Confirm linking Google account to existing account

Confirms that the authenticated user consents to linking their existing Backbuild account to the Google identity identified by `linkToken` (received from `/google-oauth` when `google_link_required` is returned).

Auth Session JWT (Bearer)

Request Body

Responses

Initiate email verification flow

Starts a passwordless registration flow by sending a verification code to the given email address. Returns a `flow_id` used in subsequent `/registration/validate` and `/complete-registration` calls. Requires a Cloudflare Turnstile token.

Auth

Request Body

Responses

Get login landing hint

Returns a hint for the login page based on the visitor's cookie and Origin/Referer headers. Used to detect returning users and determine whether the org has passwordless login enabled. Public endpoint; does not require authentication.

Auth

Responses

Log in with email and password

Authenticates a user with email and password. On success returns session tokens. If the account has MFA enabled, returns `mfa_required: true` and an `mfa_challenge_token` instead of session tokens. If the account must enroll MFA, returns `mfa_enrollment_required: true` and an `mfa_enrollment_token`. An optional `mfaDeviceToken` bypasses the interactive MFA challenge for a remembered device. Requires a Cloudflare Turnstile token.

Auth

Request Body

Responses

Log out current session

Revokes the current session's refresh token and invalidates the session. The access token remains technically valid until its short TTL expires but will fail on any endpoint that checks session state.

Auth Session JWT (Bearer)

Responses

Log out all sessions

Revokes all active sessions for the authenticated user across all devices.

Auth Session JWT (Bearer)

Responses

Look up account by email

Determines whether an email address is registered and whether passwordless (passkey) login is enabled for that account. Used by the login UI to decide which credential flow to present. Requires a valid Cloudflare Turnstile token.

Auth

Request Body

Responses

Get current user identity and first-paint data

Returns the authenticated user's full identity (profile, org, roles, permissions) together with first-paint bootstrap slices fetched in parallel. This is the primary session-bootstrap endpoint called on app load.

Auth Session JWT (Bearer)

Responses

Send a one-time password

Sends a one-time password (OTP) to the user's email for the specified purpose (`login`, `verify_email`, or `reset_password`). Rate-limited per email. Requires a Cloudflare Turnstile token.

Auth

Request Body

Responses

Verify a one-time password

Verifies the OTP sent by `/otp/create` and, if valid, returns session tokens (for `login` purpose) or confirms email/password-reset eligibility (other purposes). Requires the caller's IP address via `CF-Connecting-IP`.

Auth

Request Body

Responses

Change password

Changes the authenticated user's password. For accounts with an existing password, `old_password` is required (omit for initial password set). Requires a recent MFA step-up. On success, revokes all other sessions.

Auth Session JWT (Bearer)

Request Body

Responses

Reset password with code

Resets the user's password using the code sent to their email by `/password/reset/request`. The new password must meet complexity requirements and must not appear in known breach databases.

Auth

Request Body

Responses

Request a password reset

Sends a password-reset code to the email address if it is registered. Always returns success to prevent email enumeration. Requires a Cloudflare Turnstile token.

Auth

Request Body

Responses

Override passkey-primary login preference

Sets the authenticated user's passkey-primary login preference to `inherit` (follow org policy), `force_on` (always prompt passkey first), or `force_off` (always show password form first).

Auth Session JWT (Bearer)

Request Body

Responses

Refresh session tokens

Exchanges a valid refresh token for a new access token / refresh token pair. The old refresh token is invalidated (rotation). Returns `AUTH_REFRESH_TOKEN_INVALID` if the token has been revoked, already rotated, or is expired.

Auth

Request Body

Responses

Register a new account

Creates a new user account with email and password. Returns session tokens on success, or an `mfa_enrollment_required` flag when MFA enrollment is mandatory. Requires a Cloudflare Turnstile token. Password must meet complexity requirements (uppercase, lowercase, digit, special character) and must not appear in known breach databases.

Auth

Request Body

Responses

Validate registration verification code

Validates the verification code for an in-progress registration flow without completing it. Used to give inline feedback before the user fills in the rest of the registration form.

Auth

Request Body

Responses

Switch active environment

Issues new session tokens scoped to the specified environment within the current organization.

Auth Session JWT (Bearer)

Request Body

Responses

Switch active organization

Issues new session tokens scoped to the specified organization. The caller must be a member of the target org.

Auth Session JWT (Bearer)

Request Body

Responses

Get WebAuthn assertion options for passkey login

Returns WebAuthn assertion (get) options for the primary passkey login flow. Returns an `assertion_nonce` that must be submitted with the credential in `/webauthn/assertion/verify`.

Auth

Responses

Verify WebAuthn assertion for passkey login

Verifies a WebAuthn assertion credential against the stored passkey and the nonce issued by `/webauthn/assertion/options`. On success returns session tokens.

Auth

Request Body

Responses

Send email OTP during MFA challenge

Sends an email OTP to the user's registered email address during an active MFA challenge. Requires an MFA challenge token.

Auth Session JWT (Bearer)

Responses

Verify email OTP during MFA challenge

Verifies the email OTP sent by `/challenge/email-otp/send` during an active MFA challenge. Requires an MFA challenge token. On success returns full session tokens and optionally a device trust token.

Auth Session JWT (Bearer)

Request Body

Responses

Use recovery code during MFA challenge

Verifies a one-time recovery code during an active MFA challenge. The code is consumed and cannot be reused. Requires an MFA challenge token. On success returns full session tokens and optionally a device trust token.

Auth Session JWT (Bearer)

Request Body

Responses

Verify TOTP during MFA challenge

Verifies a TOTP code during an active MFA challenge (mid-login). Requires an MFA challenge token issued by `/login`, `/google-oauth`, or similar. On success, returns full session tokens. Optionally issues a `mfaDeviceToken` for remembered-device bypass on future logins.

Auth Session JWT (Bearer)

Request Body

Responses

Get WebAuthn options during MFA challenge

Returns WebAuthn assertion options and a `challenge_token` during an active MFA challenge. Requires an MFA challenge token.

Auth Session JWT (Bearer)

Responses

Verify WebAuthn assertion during MFA challenge

Verifies a WebAuthn assertion during an active MFA challenge. Requires an MFA challenge token. On success returns full session tokens and optionally a device trust token.

Auth Session JWT (Bearer)

Request Body

Responses

Set up email OTP MFA method

Enrolls the user's verified email address as an MFA method and sends a verification OTP. Returns recovery codes on first enrollment. Accepts either a full session JWT or an MFA enrollment token.

Auth Session JWT (Bearer)

Responses

List enrolled MFA methods

Returns all MFA methods enrolled for the authenticated user. Accepts either a full session JWT or an MFA enrollment token (issued during login when MFA enrollment is required).

Auth Session JWT (Bearer)

Responses

Rename an MFA method

Updates the display name of an enrolled MFA method.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete an MFA method

Removes an enrolled MFA method. When `force=true` is passed, requires a recent authentication and MFA step-up. Passing `force` without a recent step-up returns `MFA_STEPUP_REQUIRED`.

Auth Session JWT (Bearer)

Parameters

Responses

Generate new recovery codes

Generates a fresh set of one-time recovery codes, invalidating any previously issued codes. The returned codes are shown only once.

Auth Session JWT (Bearer)

Responses

List available step-up MFA methods

Returns the list of MFA method types available for step-up authentication for the current user.

Auth Session JWT (Bearer)

Responses

Perform TOTP step-up

Verifies a TOTP code to elevate the current session to MFA-stepped-up status. Returns a new token pair with the step-up claim. Required before sensitive operations such as password change. Only the `code` field is accepted; device-remember fields do not apply to step-up.

Auth Session JWT (Bearer)

Request Body

Responses

Get WebAuthn options for step-up

Returns WebAuthn assertion options and an HMAC-signed `challenge_token` for step-up authentication.

Auth Session JWT (Bearer)

Responses

Verify WebAuthn assertion for step-up

Verifies a WebAuthn assertion for step-up and returns a new token pair with the step-up claim.

Auth Session JWT (Bearer)

Request Body

Responses

Confirm TOTP enrollment

Verifies the first TOTP code against the encrypted secret from `/totp/setup`, completing TOTP enrollment. Returns recovery codes on first enrollment. If this is the first MFA method, also returns a full session (completing login when enrollment was required). Accepts either a full session JWT or an MFA enrollment token.

Auth Session JWT (Bearer)

Request Body

Responses

Set up TOTP MFA method

Generates a TOTP secret and URI for enrollment. The returned `encryptedSecret` must be submitted along with the first TOTP code to `/totp/confirm` to complete enrollment. Accepts either a full session JWT or an MFA enrollment token.

Auth Session JWT (Bearer)

Request Body

Responses

Get WebAuthn registration options for MFA enrollment

Returns WebAuthn attestation (create) options and a `challenge_token` for enrolling a security key or platform authenticator as an MFA method. Accepts either a full session JWT or an MFA enrollment token.

Auth Session JWT (Bearer)

Responses

Verify WebAuthn registration for MFA enrollment

Verifies the attestation response from the authenticator and stores the credential as an MFA method. Returns recovery codes on first enrollment. If this is the first MFA method and enrollment was required, also returns a full session. Accepts either a full session JWT or an MFA enrollment token.

Auth Session JWT (Bearer)

Request Body

Responses