Sign in
OpenAPI 3.1.02026-08-203914235.9 MB

6a23760847c8

Users

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.

post/users/me/oauth_grants

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

account_idstring

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.

client_idstring required

The app being authorized, prefixed app_.

code_challengestring required

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

code_challenge_method'S256' required

How code_challenge was derived. Only S256 is accepted.

consent_shownboolean

Whether the consent UI listed these scopes for the user. Sending false succeeds only when the user has already granted every scope requested.

noncestring

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

redirect_uristring 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_scopesstring[] 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.

response_type'code'

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

statestring

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

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "client_id": "app_xxxxxxxxxxxxxx",
  "code_challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "code_challenge_method": "S256",
  "consent_shown": true,
  "nonce": "n-0S6_WzA2Mj",
  "redirect_uri": "https://Booking.Shinetime.example:8443/oauth/Callback/",
  "requested_scopes": [
    "profile"
  ],
  "response_type": "code",
  "state": "opaque-client-state"
}

Response

the app is authorized

account_idstring nullable 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_idstring required

The app this grant authorizes, prefixed app_.

authorized_atstring nullable required

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

created_atstring required

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

idstring required

Grant ID, prefixed oag_.

redirect_urlstring

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.

revoked_atstring nullable 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.

scopesstring[] required

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "app_id": "app_xxxxxxxxxxxxxx",
  "authorized_at": "2026-01-01T12:00:00.000Z",
  "created_at": "2026-01-01T12:00:00.000Z",
  "id": "oag_xxxxxxxxxxxxxx",
  "redirect_url": "https://Booking.Shinetime.example:8443/oauth/Callback/",
  "revoked_at": "2026-01-01T12:00:00.000Z",
  "scopes": [
    "email"
  ]
}