> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# OAuth

> Ajoutez « Se connecter avec Whop » à votre site avec OAuth 2.1 et Proof Key for Code Exchange (PKCE).

Utilisez OAuth 2.1 + PKCE avec OpenID Connect (OIDC) pour permettre aux utilisateurs de se connecter avec Whop sur votre site web ou votre app. Les jetons d'accès renvoyés vous permettent d'accéder aux données et d'agir au nom de ces utilisateurs.

> [!NOTE]
>
> Les endpoints OAuth se trouvent à l'adresse `https://api.whop.com/oauth/`.

## Étape 1 : Créer votre app OAuth

> [!WARNING]
>
> L'objet `App` renvoyé par `apps.create` dans la version actuelle de `@whop/sdk` n'expose pas de champ `client_secret`. Copiez plutôt le secret client depuis l'onglet Dashboard.

> [tab] API
>
> Utilisez l'endpoint [Create App](https://docs.whop.com/fr/api-reference/apps/create-app.md) pour créer une app OAuth par programmation :
>
> ```typescript theme={null}
> import { WhopClient } from "@whop/sdk";
>
> const client = new WhopClient({ token: process.env.WHOP_API_KEY });
>
> const app = await client.apps.create({
>   name: "My App",
>   redirect_uris: [
>     "http://localhost:3000/api/auth/callback/whop",
>     "https://myapp.com/api/auth/callback/whop"
>   ],
> });
>
> console.log(app.id);            // NEXT_PUBLIC_WHOP_APP_ID
> console.log(app.client_secret); // WHOP_CLIENT_SECRET
> ```
>
> Mettez à jour les URI de redirection plus tard avec l'endpoint [Update App](https://docs.whop.com/fr/api-reference/apps/update-app.md).

> [tab] Dashboard
>
> **1. Créez ou sélectionnez votre app**
>
> Accédez au [tableau de bord développeur](https://whop.com/dashboard/developer), puis créez une nouvelle app ou sélectionnez-en une existante.
>
> **2. Ajoutez les URI de redirection**
>
> Dans la section OAuth, ajoutez chaque URI de redirection que vous prévoyez d'utiliser (correspondance exacte requise).
>
> **3. Copiez les identifiants**
>
> Copiez votre `client_id` (au format `app_xxxxx`) et votre `client_secret`.
>
> **4. Sélectionnez vos scopes**
>
> Affichez les scopes OAuth disponibles avec le bouton « View available scopes » et sélectionnez uniquement ceux dont vous avez besoin.

## Étape 2 : Rediriger les utilisateurs vers l'autorisation

Dans votre client web ou mobile, utilisez PKCE pour rediriger de manière sécurisée les utilisateurs vers le flux OAuth de Whop.

```typescript expandable theme={null}
const STORAGE_KEY = "whop_oauth_pkce";

function base64url(bytes: Uint8Array) {
	return btoa(String.fromCharCode(...bytes)).replace(
		/[+/=]/g,
		(c) => ({ "+": "-", "/": "_", "=": "" })[c]!,
	);
}

function randomString(len: number) {
	return base64url(crypto.getRandomValues(new Uint8Array(len)));
}

async function sha256(str: string) {
	return base64url(
		new Uint8Array(
			await crypto.subtle.digest("SHA-256", new TextEncoder().encode(str)),
		),
	);
}

async function startWhopOAuth(
	clientId: string,
	redirectUri: string,
	scope = "openid profile email",
	accountId?: string,
) {
	const pkce = {
		codeVerifier: randomString(32),
		state: randomString(16),
		nonce: randomString(16),
	};
	sessionStorage.setItem(STORAGE_KEY, JSON.stringify(pkce));

	const params = new URLSearchParams({
		response_type: "code",
		client_id: clientId,
		redirect_uri: redirectUri,
		scope,
		state: pkce.state,
		nonce: pkce.nonce,
		code_challenge: await sha256(pkce.codeVerifier),
		code_challenge_method: "S256",
		...(accountId && { company_id: accountId }),
	});

	window.location.href = `https://api.whop.com/oauth/authorize?${params}`;
}
```

Appelez `startWhopOAuth` pour rediriger l'utilisateur :

```typescript theme={null}
await startWhopOAuth(
	"app_xxxxxxxxx",
	"https://yourapp.com/oauth/callback",
	"openid profile email", // optionally specify more custom scopes here
	"biz_xxxxx", // optionally specify a scoped account id here
);
```

Si l'utilisateur n'est pas connecté, Whop lui demande de se connecter, puis affiche l'écran de consentement.
Si l'utilisateur a déjà approuvé votre application pour les scopes demandés,
il est automatiquement redirigé sans avoir à confirmer une seconde fois.

> [!NOTE]
>
> Si vous passez un ID de compte en tant que `company_id`, les jetons sont limités à ce compte
> pour l'utilisateur. Vous ne pouvez accéder qu'aux ressources que l'utilisateur peut contrôler sur
> ce compte Whop.

## Étape 3 : Gérer le callback et échanger le code

Whop redirige vers votre `redirect_uri` avec `code` et `state`. Utilisez cette fonction pour vérifier le state, échanger le code contre des jetons et récupérer les identifiants :

```typescript expandable theme={null}
const STORAGE_KEY = "whop_oauth_pkce";

interface WhopTokens {
	access_token: string;
	refresh_token: string;
	id_token?: string; // only present if "openid" scope was requested
	token_type: string;
	expires_in: number;
	obtained_at: number; // we add this client-side for refresh logic
}

async function handleWhopCallback(
	clientId: string,
	redirectUri: string,
): Promise<WhopTokens> {
	const params = new URLSearchParams(window.location.search);
	const [code, returnedState, error] = [
		params.get("code"),
		params.get("state"),
		params.get("error"),
	];
	if (error)
		throw new Error(
			`OAuth error: ${error} - ${params.get("error_description") || ""}`,
		);

	const stored = JSON.parse(sessionStorage.getItem(STORAGE_KEY) || "null");
	sessionStorage.removeItem(STORAGE_KEY);
	if (!stored || returnedState !== stored.state)
		throw new Error("Invalid state - possible CSRF");

	const res = await fetch("https://api.whop.com/oauth/token", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({
			grant_type: "authorization_code",
			code,
			redirect_uri: redirectUri,
			client_id: clientId,
			code_verifier: stored.codeVerifier,
		}),
	});

	if (!res.ok) {
		const err = await res.json().catch(() => ({}));
		throw new Error(
			`Token exchange failed: ${err.error_description || res.status}`,
		);
	}

	const tokens = await res.json();
	return { ...tokens, obtained_at: Date.now() };
}

function storeTokens(tokens: WhopTokens) {
	document.cookie = `whop_tokens=${encodeURIComponent(JSON.stringify(tokens))}; path=/; max-age=${60 * 60 * 24 * 30}; secure; samesite=strict`;
}

function getTokens(): WhopTokens | null {
	const match = document.cookie.match(/whop_tokens=([^;]+)/);
	return match ? JSON.parse(decodeURIComponent(match[1])) : null;
}

function clearTokens() {
	document.cookie = "whop_tokens=; path=/; max-age=0";
}
```

Sur votre page de callback :

```typescript theme={null}
const tokens = await handleWhopCallback(
	"app_xxxxxxxxx",
	"https://yourapp.com/oauth/callback",
);
storeTokens(tokens);
```

## Étape 4 : Utiliser les jetons

Initialisez le SDK Whop avec le jeton d'accès de l'utilisateur :

```typescript theme={null}
import { WhopClient } from "@whop/sdk";

const tokens = getTokens();

const client = new WhopClient({
	token: tokens.access_token,
});
```

Consultez la [référence API](https://docs.whop.com/fr/api-reference/overview.md) pour voir tous les endpoints disponibles.

## Étape 5 : Rafraîchir les jetons

Les jetons d'accès expirent au bout d'une heure. Utilisez le jeton de rafraîchissement pour obtenir de nouveaux identifiants :

```typescript expandable theme={null}
async function refreshTokens(
	clientId: string,
	accountId?: string,
): Promise<WhopTokens> {
	const tokens = getTokens();
	if (!tokens?.refresh_token) throw new Error("No refresh token available");

	const res = await fetch("https://api.whop.com/oauth/token", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({
			grant_type: "refresh_token",
			refresh_token: tokens.refresh_token,
			client_id: clientId,
			...(accountId && { company_id: accountId }),
		}),
	});

	if (!res.ok) {
		const error = await res.json().catch(() => ({}));
		if (res.status === 401 || error.error === "invalid_grant") {
			clearTokens();
			throw new Error("Session expired - please log in again");
		}
		throw new Error(
			`Token refresh failed: ${error.error_description || res.status}`,
		);
	}

	const newTokens = await res.json();
	const stored = { ...newTokens, obtained_at: Date.now() };
	storeTokens(stored);
	return stored;
}

async function getValidAccessToken(clientId: string): Promise<string> {
	const tokens = getTokens();
	if (!tokens) throw new Error("Not logged in");

	const expiresAt = tokens.obtained_at + tokens.expires_in * 1000;
	const needsRefresh = Date.now() > expiresAt - 5 * 60 * 1000; // 5 min buffer

	if (needsRefresh) {
		const refreshed = await refreshTokens(clientId);
		return refreshed.access_token;
	}

	return tokens.access_token;
}
```

Utilisation :

```typescript theme={null}
const accessToken = await getValidAccessToken("app_xxxxxxxxx");
```

> [!NOTE]
>
> Les jetons de rafraîchissement changent à chaque utilisation. Stockez toujours les nouveaux jetons renvoyés par
> l'endpoint de rafraîchissement. Si vous avez fourni `company_id` lors de l'autorisation, vous
> devez fournir le même `company_id` lors du rafraîchissement.

## Étape 6 : Userinfo et révocation

### Obtenir les informations de l'utilisateur

Récupérez le profil de l'utilisateur authentifié avec l'endpoint userinfo :

```typescript theme={null}
interface WhopUserInfo {
	sub: string; // user tag (e.g. "user_xxxxx")
	name?: string; // requires "profile" scope
	preferred_username?: string; // requires "profile" scope
	picture?: string; // requires "profile" scope
	email?: string; // requires "email" scope
	email_verified?: boolean; // requires "email" scope
}

async function getUserInfo(accessToken: string): Promise<WhopUserInfo> {
	const res = await fetch("https://api.whop.com/oauth/userinfo", {
		headers: { Authorization: `Bearer ${accessToken}` },
	});
	if (!res.ok) throw new Error(`Failed to fetch user info: ${res.status}`);
	return res.json();
}
```

> [!NOTE]
>
> Les champs renvoyés dépendent des scopes accordés. `openid` est requis,
> `profile` ajoute le nom, le nom d'utilisateur et la photo, `email` ajoute les champs d'e-mail.

### Révoquer les jetons à la déconnexion

Lorsqu'un utilisateur se déconnecte, révoquez son jeton de rafraîchissement. Les jetons d'accès expirent au bout d'une heure et ne peuvent pas être révoqués côté serveur.

```typescript theme={null}
async function logout(clientId: string) {
	const tokens = getTokens();
	if (tokens?.refresh_token) {
		await fetch("https://api.whop.com/oauth/revoke", {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({
				token: tokens.refresh_token,
				client_id: clientId,
			}),
		});
	}
	clearTokens();
}
```

> [!WARNING]
>
> Révoquez toujours les jetons lorsque les utilisateurs se déconnectent. Cela invalide immédiatement le jeton de rafraîchissement,
> ce qui empêche tout accès non autorisé même si le jeton a été compromis.

## Gestion des erreurs

Les erreurs OAuth suivent le format standard :

```json theme={null}
{
	"error": "invalid_grant",
	"error_description": "Authorization code has expired"
}
```

Codes d'erreur courants :

* `invalid_request` : paramètre manquant ou invalide.
* `invalid_grant` : code ou jeton expiré ou révoqué.
* `invalid_client` : `client_id` inconnu.
* `insufficient_scope` : le jeton ne dispose pas du scope requis.
* `rate_limit_exceeded` : trop de requêtes (vérifiez l'en-tête `Retry-After`).

## Étapes suivantes

> [card] [Référence API](https://docs.whop.com/fr/api-reference.md)
>
> Tous les endpoints qu'un jeton d'accès accordé peut appeler.

> [card] [Accepter des paiements](https://docs.whop.com/fr/developer/guides/accept-payments.md)
>
> Associez la connexion au checkout pour des parcours d'achat de bout en bout.

> [card] [Écouter les webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md)
>
> Réagissez côté serveur aux événements de paiement, d'adhésion et d'inscription.

> [card] [Demander des autorisations](https://docs.whop.com/fr/developer/guides/permissions.md)
>
> Configurez les scopes OAuth dont votre app a réellement besoin.


## Related topics

- [Authentification du chat](https://docs.whop.com/fr/developer/guides/chat/authentication.md)
- [List OAuth Grants](https://docs.whop.com/fr/api-reference/users/list-oauth-grants.md)
- [OAuth pour le chat](https://docs.whop.com/fr/developer/guides/chat/oauth.md)
