> ## 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

> OAuth 2.1 ve Proof Key for Code Exchange (PKCE) ile sitenize "Whop ile oturum aç" özelliğini ekleyin.

Kullanıcıların web sitenizde veya uygulamanızda Whop ile oturum açmasını sağlamak için OAuth 2.1 + PKCE'yi OpenID Connect (OIDC) ile birlikte kullanın. Döndürülen erişim token'ları, verilere erişmenizi ve bu kullanıcılar adına işlem yapmanızı sağlar.

> [!NOTE]
>
> OAuth uç noktaları `https://api.whop.com/oauth/` adresinde bulunur.

## Adım 1: OAuth uygulamanızı oluşturun

> [!WARNING]
>
> Güncel `@whop/sdk` içindeki `apps.create` tarafından döndürülen `App` nesnesi bir `client_secret` alanı sunmaz. Bunun yerine istemci sırrını Dashboard sekmesinden kopyalayın.

> [tab] API
>
> Programatik olarak bir OAuth uygulaması oluşturmak için [Create App](https://docs.whop.com/tr/api-reference/apps/create-app.md) uç noktasını kullanın:
>
> ```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
> ```
>
> Yönlendirme URI'lerini daha sonra [Update App](https://docs.whop.com/tr/api-reference/apps/update-app.md) uç noktasıyla güncelleyin.

> [tab] Dashboard
>
> **1. Uygulamanızı oluşturun veya seçin**
>
> [Geliştirici panosuna](https://whop.com/dashboard/developer) gidin, ardından yeni bir uygulama oluşturun veya mevcut bir uygulamayı seçin.
>
> **2. Yönlendirme URI'lerini ekleyin**
>
> OAuth bölümünde kullanmayı planladığınız her yönlendirme URI'sini ekleyin (birebir eşleşme gerekir).
>
> **3. Kimlik bilgilerini kopyalayın**
>
> `client_id` (`app_xxxxx` biçiminde) ve `client_secret` değerlerinizi kopyalayın.
>
> **4. Kapsamlarınızı seçin**
>
> "View available scopes" düğmesinden kullanılabilir OAuth kapsamlarınızı görüntüleyin ve yalnızca ihtiyacınız olanları seçin.

## Adım 2: Kullanıcıları yetkilendirmeye gönderin

Web veya mobil istemcinizde, kullanıcıları güvenli bir şekilde Whop'un OAuth akışına yönlendirmek için PKCE kullanın.

```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}`;
}
```

Kullanıcıyı yönlendirmek için `startWhopOAuth` çağırın:

```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
);
```

Kullanıcı oturum açmamışsa Whop oturum açmasını ister, ardından onay ekranını gösterir.
Kullanıcı uygulamanızı istenen kapsamlar için zaten onaylamışsa,
iki kez onaylamasına gerek kalmadan otomatik olarak geri yönlendirilir.

> [!NOTE]
>
> `company_id` olarak bir hesap kimliği iletirseniz token'lar kullanıcı için o hesapla
> sınırlandırılır. Yalnızca kullanıcının o Whop hesabında kontrol edebildiği
> kaynaklara erişebilirsiniz.

## Adım 3: Geri çağrıyı işleyin ve kodu takas edin

Whop, `code` ve `state` ile `redirect_uri` adresinize geri yönlendirir. State'i doğrulamak, kodu token'larla takas etmek ve kimlik bilgilerini almak için bu fonksiyonu kullanın:

```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";
}
```

Geri çağrı sayfanızda:

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

## Adım 4: Token'ları kullanın

Whop SDK'sını kullanıcının erişim token'ı ile başlatın:

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

const tokens = getTokens();

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

Kullanılabilir tüm uç noktaları görmek için [API referansına](https://docs.whop.com/tr/api-reference/overview.md) bakın.

## Adım 5: Token'ları yenileyin

Erişim token'larının süresi 1 saat sonra dolar. Yeni kimlik bilgileri almak için yenileme token'ını kullanın:

```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;
}
```

Kullanım:

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

> [!NOTE]
>
> Yenileme token'ları her kullanımda değişir. Yenileme uç noktasından döndürülen yeni
> token'ları her zaman saklayın. Yetkilendirme sırasında `company_id` sağladıysanız,
> yenileme sırasında da aynı `company_id` değerini sağlamanız gerekir.

## Adım 6: Kullanıcı bilgisi ve iptal

### Kullanıcı bilgisini alın

Kimliği doğrulanmış kullanıcının profilini userinfo uç noktasını kullanarak getirin:

```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]
>
> Döndürülen alanlar verilen kapsamlara bağlıdır. `openid` zorunludur,
> `profile` ad/kullanıcı adı/resim ekler, `email` e-posta alanlarını ekler.

### Oturum kapatılırken token'ları iptal edin

Bir kullanıcı oturumu kapattığında yenileme token'ını iptal edin. Erişim token'larının süresi 1 saat sonra dolar ve sunucu tarafında iptal edilemezler.

```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]
>
> Kullanıcılar oturumu kapattığında token'ları her zaman iptal edin. Bu, yenileme token'ını
> anında geçersiz kılar ve token ele geçirilmiş olsa bile yetkisiz erişimi önler.

## Hata işleme

OAuth hataları standart biçimi izler:

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

Yaygın hata kodları:

* `invalid_request`: eksik veya geçersiz parametre.
* `invalid_grant`: kodun veya token'ın süresi dolmuş ya da iptal edilmiş.
* `invalid_client`: bilinmeyen `client_id`.
* `insufficient_scope`: token gerekli kapsama sahip değil.
* `rate_limit_exceeded`: çok fazla istek (`Retry-After` başlığını kontrol edin).

## Sonraki adımlar

> [card] [API referansı](https://docs.whop.com/tr/api-reference.md)
>
> Verilen bir erişim token'ının çağırabileceği her uç nokta.

> [card] [Ödeme kabul edin](https://docs.whop.com/tr/developer/guides/accept-payments.md)
>
> Uçtan uca satın alma akışları için oturum açmayı ödeme sayfasıyla birleştirin.

> [card] [Webhook'ları dinleyin](https://docs.whop.com/tr/developer/guides/webhooks.md)
>
> Ödeme, üyelik ve giriş olaylarına sunucu tarafında tepki verin.

> [card] [İzin isteyin](https://docs.whop.com/tr/developer/guides/permissions.md)
>
> Uygulamanızın gerçekten ihtiyaç duyduğu OAuth kapsamlarını yapılandırın.


## Related topics

- [Sohbet Kimlik Doğrulaması](https://docs.whop.com/tr/developer/guides/chat/authentication.md)
- [Sohbet OAuth](https://docs.whop.com/tr/developer/guides/chat/oauth.md)
- [List OAuth Grants](https://docs.whop.com/tr/api-reference/users/list-oauth-grants.md)
