Users

Authorize an App

Changed on

Completes the OAuth authorization step for the authenticated user: records their consent to the scopes an app asked for and mints an authorization code. Returns the grant plus a redirect_url carrying the code, which is returned only this once; the app exchanges it at POST /oauth/token. 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 so a retry returns the original redirect_url and code instead of issuing a second one.

post/users/me/oauth_grants

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/users/me/oauth_grants
  • Auth: HTTP bearer

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

The PKCE code challenge: the base64url-encoded SHA-256 of your code verifier, without padding. Required unless the app is confidential; a confidential app that leaves it out redeems the code with its secret instead of a verifier.

code_challenge_method'S256'

How code_challenge was derived. Only S256 is accepted. Required with code_challenge.

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, or when the app is one of Whop's own with the consent skip switched on and asks for openid alone.

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"
  ]
}

Changes