Authorize an App
Completes the OAuth authorization step for the authenticated user: records their consent for the scopes an app asked for and mints the authorization code to hand back to it. Returns the grant, plus a redirect_url carrying that code — the one and only time it is returned. Exchange the code at POST /oauth/token with the verifier for code_challenge. Requires a user session, because consent has to come from the account holder: an API key or an OAuth token is refused, so an app can never authorize itself. Send an Idempotency-Key to make a retry safe — a replay returns the original redirect_url and its code rather than issuing a second one.
Authorizations
An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.
Headers
A unique key that makes this request safe to retry. See Idempotent requests.
255"d9105228-4a08-46b1-8b91-42fed586d383"
Pins the request to a dated API version.
"2026-08-03"
Body
The app being authorized, prefixed app_.
The PKCE code challenge: the base64url-encoded SHA-256 of your code verifier, without padding.
How code_challenge was derived. Only S256 is accepted.
S256 Where to send the user once they have consented. Must match one of the app's registered redirect URIs exactly — it is compared as a string, not normalized.
The permissions the app is asking for, for example member:basic:read. GET /api_keys/permissions names and describes each one. Granting adds to whatever the user already granted this app rather than replacing it.
Authorize the app for one of the user's accounts rather than for the user alone, prefixed biz_. The user must have access to it.
Whether the consent UI listed these scopes for the user. Sending false succeeds only when the user has already granted every scope requested.
OIDC nonce, echoed into the resulting ID token. Required when requested_scopes includes openid.
The OAuth response type. Only code is accepted; defaults to code.
code Opaque value appended to redirect_url unchanged, for the client to correlate the response with its request.
Response
the app is authorized
The account the grant is scoped to, prefixed biz_. null when the user authorized the app for themselves rather than for one of their accounts.
The app this grant authorizes, prefixed app_.
When the user last authorized the app, as an ISO 8601 timestamp.
When the user first authorized the app, as an ISO 8601 timestamp.
Grant ID, prefixed oag_.
When the grant was revoked, as an ISO 8601 timestamp, or null while it is still in force. A revoked grant authorizes nothing — treat its scopes as no longer granted.
Every permission the user has granted this app, accumulated across authorizations, for example member:basic:read. GET /api_keys/permissions names and describes each one.
Where to send the user to finish the flow: the redirect_uri you supplied with the authorization code appended, and state when you supplied one. Its scheme, host, port, and path come back exactly as sent — never re-cased or re-encoded — because the client matches them against its registered URI. Returned only once, on create: the code is single-use and expires 10 minutes after it is issued, so redirect immediately.

