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

JavaScript

JavaScript

import Whop from '@whop/sdk';

const client = new Whop({
  apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
});

const oauthGrant = await client.users.oauthGrants.create({
  client_id: 'app_xxxxxxxxxxxxxx',
  code_challenge: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  code_challenge_method: 'S256',
  redirect_uri: 'https://Booking.Shinetime.example:8443/oauth/Callback/',
  requested_scopes: ['profile'],
});

console.log(oauthGrant.id);

201

{
  "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",
  "revoked_at": "2026-01-01T12:00:00.000Z",
  "scopes": [
    "email"
  ],
  "redirect_url": "https://Booking.Shinetime.example:8443/oauth/Callback/"
}

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-21"

Body

application/json

client_id · string · required

The app being authorized, prefixed app_.

Example:

"app_xxxxxxxxxxxxxx"

code_challenge · string · required

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

Example:

"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

code_challenge_method · enum<string> · required

How code_challenge was derived. Only S256 is accepted.

Available options: S256

Example:

"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.

Example:

"https://Booking.Shinetime.example:8443/oauth/Callback/"

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.

Example:

"biz_xxxxxxxxxxxxxx"

consent_shown · boolean · default: true

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

Example:

true

nonce · string

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

Example:

"n-0S6_WzA2Mj"

response_type · enum<string>

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

Available options: code

Example:

"code"

state · string

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

Example:

"opaque-client-state"

Response

201

application/json

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.

Example:

"biz_xxxxxxxxxxxxxx"

app_id · string · required

The app this grant authorizes, prefixed app_.

Example:

"app_xxxxxxxxxxxxxx"

authorized_at · string | null · required

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

Example:

"2026-01-01T12:00:00.000Z"

created_at · string · required

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

Example:

"2026-01-01T12:00:00.000Z"

id · string · required

Grant ID, prefixed oag_.

Example:

"oag_xxxxxxxxxxxxxx"

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.

Example:

"2026-01-01T12:00:00.000Z"

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.

Example:

"https://Booking.Shinetime.example:8443/oauth/Callback/"