Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-08-03"

Body

application/json
client_id
string
required

The app being authorized, prefixed app_.

code_challenge
string
required

The PKCE code challenge: the base64url-encoded SHA-256 of your code verifier, without padding.

code_challenge_method
enum<string>
required

How code_challenge was derived. Only S256 is accepted.

Available options:
S256
redirect_uri
string
required

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.

requested_scopes
string[]
required

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.

account_id
string

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.

nonce
string

OIDC nonce, echoed into the resulting ID token. Required when requested_scopes includes openid.

response_type
enum<string>

The OAuth response type. Only code is accepted; defaults to code.

Available options:
code
state
string

Opaque value appended to redirect_url unchanged, for the client to correlate the response with its request.

Response

the app is authorized

account_id
string | null
required

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.

app_id
string
required

The app this grant authorizes, prefixed app_.

authorized_at
string | null
required

When the user last authorized the app, as an ISO 8601 timestamp.

created_at
string
required

When the user first authorized the app, as an ISO 8601 timestamp.

id
string
required

Grant ID, prefixed oag_.

revoked_at
string | null
required

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.

scopes
string[]
required

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.

redirect_url
string

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.