TypeScript

import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: "YOUR_TOKEN", apiVersionDate: "2026-08-21-1", idempotencyKey: "YOUR_IDEMPOTENCY_KEY" });
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"]
});

curl --request POST \
  --url https://api.whop.com/api/v1/users/me/oauth_grants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "app_xxxxxxxxxxxxxx",
  "redirect_uri": "https://Booking.Shinetime.example:8443/oauth/Callback/",
  "requested_scopes": [
    "profile"
  ],
  "account_id": "biz_xxxxxxxxxxxxxx",
  "code_challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "code_challenge_method": "S256",
  "consent_shown": true,
  "nonce": "n-0S6_WzA2Mj",
  "response_type": "code",
  "state": "opaque-client-state"
}
'

import requests

url = "https://api.whop.com/api/v1/users/me/oauth_grants"

payload = {
    "client_id": "app_xxxxxxxxxxxxxx",
    "redirect_uri": "https://Booking.Shinetime.example:8443/oauth/Callback/",
    "requested_scopes": ["profile"],
    "account_id": "biz_xxxxxxxxxxxxxx",
    "code_challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "code_challenge_method": "S256",
    "consent_shown": True,
    "nonce": "n-0S6_WzA2Mj",
    "response_type": "code",
    "state": "opaque-client-state"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_id: 'app_xxxxxxxxxxxxxx',
    redirect_uri: 'https://Booking.Shinetime.example:8443/oauth/Callback/',
    requested_scopes: ['profile'],
    account_id: 'biz_xxxxxxxxxxxxxx',
    code_challenge: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    code_challenge_method: 'S256',
    consent_shown: true,
    nonce: 'n-0S6_WzA2Mj',
    response_type: 'code',
    state: 'opaque-client-state'
  })
};

fetch('https://api.whop.com/api/v1/users/me/oauth_grants', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.whop.com/api/v1/users/me/oauth_grants",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'client_id' => 'app_xxxxxxxxxxxxxx',
    'redirect_uri' => 'https://Booking.Shinetime.example:8443/oauth/Callback/',
    'requested_scopes' => [
        'profile'
    ],
    'account_id' => 'biz_xxxxxxxxxxxxxx',
    'code_challenge' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'code_challenge_method' => 'S256',
    'consent_shown' => true,
    'nonce' => 'n-0S6_WzA2Mj',
    'response_type' => 'code',
    'state' => 'opaque-client-state'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.whop.com/api/v1/users/me/oauth_grants"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.whop.com/api/v1/users/me/oauth_grants")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_id\": \"app_xxxxxxxxxxxxxx\",\n  \"redirect_uri\": \"https://Booking.Shinetime.example:8443/oauth/Callback/\",\n  \"requested_scopes\": [\n    \"profile\"\n  ],\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"code_challenge\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  \"code_challenge_method\": \"S256\",\n  \"consent_shown\": true,\n  \"nonce\": \"n-0S6_WzA2Mj\",\n  \"response_type\": \"code\",\n  \"state\": \"opaque-client-state\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.whop.com/api/v1/users/me/oauth_grants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"client_id\": \"app_xxxxxxxxxxxxxx\",\n  \"redirect_uri\": \"https://Booking.Shinetime.example:8443/oauth/Callback/\",\n  \"requested_scopes\": [\n    \"profile\"\n  ],\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"code_challenge\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  \"code_challenge_method\": \"S256\",\n  \"consent_shown\": true,\n  \"nonce\": \"n-0S6_WzA2Mj\",\n  \"response_type\": \"code\",\n  \"state\": \"opaque-client-state\"\n}"

response = http.request(request)
puts response.read_body

{
  "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/"
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

OAuth Grants

Authorize an App

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

oauth_grants

TypeScript

import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: "YOUR_TOKEN", apiVersionDate: "2026-08-21-1", idempotencyKey: "YOUR_IDEMPOTENCY_KEY" });
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"]
});

curl --request POST \
  --url https://api.whop.com/api/v1/users/me/oauth_grants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "app_xxxxxxxxxxxxxx",
  "redirect_uri": "https://Booking.Shinetime.example:8443/oauth/Callback/",
  "requested_scopes": [
    "profile"
  ],
  "account_id": "biz_xxxxxxxxxxxxxx",
  "code_challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "code_challenge_method": "S256",
  "consent_shown": true,
  "nonce": "n-0S6_WzA2Mj",
  "response_type": "code",
  "state": "opaque-client-state"
}
'

import requests

url = "https://api.whop.com/api/v1/users/me/oauth_grants"

payload = {
    "client_id": "app_xxxxxxxxxxxxxx",
    "redirect_uri": "https://Booking.Shinetime.example:8443/oauth/Callback/",
    "requested_scopes": ["profile"],
    "account_id": "biz_xxxxxxxxxxxxxx",
    "code_challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "code_challenge_method": "S256",
    "consent_shown": True,
    "nonce": "n-0S6_WzA2Mj",
    "response_type": "code",
    "state": "opaque-client-state"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_id: 'app_xxxxxxxxxxxxxx',
    redirect_uri: 'https://Booking.Shinetime.example:8443/oauth/Callback/',
    requested_scopes: ['profile'],
    account_id: 'biz_xxxxxxxxxxxxxx',
    code_challenge: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    code_challenge_method: 'S256',
    consent_shown: true,
    nonce: 'n-0S6_WzA2Mj',
    response_type: 'code',
    state: 'opaque-client-state'
  })
};

fetch('https://api.whop.com/api/v1/users/me/oauth_grants', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.whop.com/api/v1/users/me/oauth_grants",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'client_id' => 'app_xxxxxxxxxxxxxx',
    'redirect_uri' => 'https://Booking.Shinetime.example:8443/oauth/Callback/',
    'requested_scopes' => [
        'profile'
    ],
    'account_id' => 'biz_xxxxxxxxxxxxxx',
    'code_challenge' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'code_challenge_method' => 'S256',
    'consent_shown' => true,
    'nonce' => 'n-0S6_WzA2Mj',
    'response_type' => 'code',
    'state' => 'opaque-client-state'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.whop.com/api/v1/users/me/oauth_grants"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.whop.com/api/v1/users/me/oauth_grants")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_id\": \"app_xxxxxxxxxxxxxx\",\n  \"redirect_uri\": \"https://Booking.Shinetime.example:8443/oauth/Callback/\",\n  \"requested_scopes\": [\n    \"profile\"\n  ],\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"code_challenge\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  \"code_challenge_method\": \"S256\",\n  \"consent_shown\": true,\n  \"nonce\": \"n-0S6_WzA2Mj\",\n  \"response_type\": \"code\",\n  \"state\": \"opaque-client-state\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.whop.com/api/v1/users/me/oauth_grants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"client_id\": \"app_xxxxxxxxxxxxxx\",\n  \"redirect_uri\": \"https://Booking.Shinetime.example:8443/oauth/Callback/\",\n  \"requested_scopes\": [\n    \"profile\"\n  ],\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"code_challenge\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  \"code_challenge_method\": \"S256\",\n  \"consent_shown\": true,\n  \"nonce\": \"n-0S6_WzA2Mj\",\n  \"response_type\": \"code\",\n  \"state\": \"opaque-client-state\"\n}"

response = http.request(request)
puts response.read_body

{
  "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/"
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Only available to a signed-in whop.com session. API keys, access tokens, and OAuth tokens are not accepted.

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-10-15-1"

Body

application/json

client_id

string

required

The app being authorized, prefixed app_.

Example:

"app_xxxxxxxxxxxxxx"

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"

code_challenge

string

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.

Example:

"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

code_challenge_method

enum<string>

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

Available options:

S256

Example:

"S256"

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.

Example:

true

mcp_client

object

The downstream MCP client displayed on the consent screen. Requires explicit consent even when the upstream app already has a grant. Bound to the authorization code and returned on token exchange so the MCP server can verify the approved client.

Show child attributes

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

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"

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

Introduction

Reference

Core Resources

Payments

Money

Commerce

Websites

Ads

Analytics

Communication

Partners

Workforce

Media

Developer

Authorize an App

Authorizations

Headers

Body

Response