oauth

Issue an authorization code after explicit user consent.

Changed on

The browser calls this endpoint from the consent page when the user clicks "Allow". The endpoint:

  1. Validates the requested scopes and key name shape (mirroring the self-service API key endpoint), so we reject obvious mistakes before issuing the code.
  2. Validates the callback URL scheme and host against auth.oauth_pkce.allowed_domains / denied_domains.
  3. Persists a single-use authorization code bound to the current user and the supplied PKCE challenge.
  4. Returns the redirect URL the page should send the browser to.
post/admin/v1/oauth/authorize

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /admin/v1/oauth/authorize
  • Auth: HTTP bearer

Request body

app_namestring nullable

Optional human-readable name of the requesting app, shown on the consent screen.

callback_urlstring required

Where the external app expects the user to land after consent. The exchange endpoint requires this exact same value when redeeming.

code_challengestring required

PKCE challenge supplied by the external app. RFC 7636 §4.1 mandates 43–128 characters for both the verifier and (by extension) the S256 / plain challenges.

code_challenge_method'S256' | 'plain' required

PKCE code challenge method supplied by the external app.

Response

Authorization code issued

codestring required

Authorization code to forward to the external app via callback_url?code=....

expires_atstring date-time required

When the code expires; the exchange must complete before this time.

redirect_urlstring required

Fully-formed redirect URL (callback_url with the code query parameter).

Changes