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

# 인증 및 API 키

> Whop의 다섯 가지 자격 증명 유형, 각각을 언제 사용하는지, 그리고 자격 증명의 범위를 실제로 필요한 작업으로 좁히는 방법을 알아보세요.

Whop에는 다섯 가지 자격 증명 유형이 있습니다. 어떤 것이 필요한지는 누구의 데이터에 접근하는지와 코드가 어디에서 실행되는지에 따라 달라집니다. 이 표에서 선택한 다음, 프로덕션에 가까이 가기 전에 자격 증명의 범위를 좁히세요.

| 자격 증명 | 대리하는 주체 | 위치 | 사용 시점 |
| - | - | - | - |
| **API 키** | 내 계정 또는 내 앱 | 내 서버 | 백엔드가 내 계정, 또는 내 앱을 설치한 모든 계정에 접근할 때 |
| **계정 범위 사용자 토큰** | 하나의 계정 안에 있는 한 명의 사용자 | 서버에서 발급하고 클라이언트에서 사용 | 제품에 이미 자체 사용자가 있고, 그 사용자들이 Whop 로그인 없이 Whop에 접근해야 할 때 |
| **계정 액세스 토큰** | 권한이 좁혀진 내 계정 | 서버에서 발급하고 클라이언트에서 사용 | 클라이언트가 API 키를 보유하지 않고 내 계정에 단기간 접근해야 할 때 |
| **iframe 사용자 토큰** | 앱을 보고 있는 사용자 | Whop이 전송하고 내가 검증 | 앱이 Whop 안에서 렌더링되고 누가 보고 있는지 알아야 할 때 |
| **OAuth 토큰** | Whop에 로그인한 사용자 | OAuth 흐름 후 내 서버 | 사용자가 Whop으로 로그인하고 앱에 자신의 계정 접근 권한을 부여하게 하려는 경우 |

## API 키

계정 API 키는 서버를 하나의 계정으로 인증합니다. 앱 API 키는 앱을 설치한 모든 계정에서 앱을 인증합니다. 둘 다 비밀 정보이므로 서버 측에 보관하세요.

### 계정 API 키 생성하기

서버가 내 계정과 그 [하위 계정](https://docs.whop.com/ko/developer/platforms/enroll-subaccounts.md)을 대신해 작업할 때 계정 API 키를 사용하세요. 대시보드의 Developer 페이지에서 **Account API Keys**를 열고 **Create**를 선택합니다. [빠른 시작](https://docs.whop.com/ko/developer/quickstart.md)에서 샌드박스로 과정을 안내합니다.

### 앱 API 키 생성하기

앱을 빌드하고 앱을 설치한 계정의 데이터에 접근해야 할 때 앱 API 키를 사용하세요.

1. 대시보드에서 **Apps**를 엽니다.
2. **Create app**을 선택하고 앱 이름을 지정합니다. 이름은 나중에 변경할 수 있습니다.
3. 키는 **Environment variables** 섹션에서 `WHOP_API_KEY` 뒤에 숨겨진 값입니다. 표시 버튼으로 값을 확인한 다음 안전한 곳에 저장하세요.

## 계정 범위 사용자 토큰

계정 범위 사용자 토큰은 특정 계정 안에서 특정 사용자 한 명으로 동작합니다. 서버가 API 키로 이 토큰을 발급해 클라이언트에 전달하므로, 사용자는 Whop에 로그인하지 않고도 Whop에 접근할 수 있습니다.

`POST /api/v1/access_tokens`로 생성하며 `account_id`, `user_id`, 허용할 작업을 전달합니다:

```bash theme={null}
curl https://api.whop.com/api/v1/access_tokens \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "biz_XXXXXXXX",
    "user_id": "user_XXXXXXXX",
    "scoped_actions": ["chat:read", "chat:message:create"]
  }'
```

`account_id`는 `biz_`로, `user_id`는 `user_`로 시작합니다. API 키에는 둘 다에 접근할 권한이 있어야 합니다.

토큰은 기본적으로 **1시간** 후에 만료됩니다. `expires_at`을 설정하면 최대 **3시간**까지 변경할 수 있습니다. 토큰을 캐시하지 말고 필요할 때마다 발급하세요.

> [!NOTE]
>
> [액세스 토큰 생성](https://docs.whop.com/ko/api-reference/legacy/access-tokens/create-access-token.md)을 참고하세요.

### 토큰 범위 지정하기

`scoped_actions`는 토큰이 할 수 있는 작업의 목록입니다. 각 항목은 콜론으로 구분된 작업 문자열입니다.

> [!WARNING]
>
> `scoped_actions`를 비워 두거나 생략하면 토큰은 **발급한 자격 증명의 모든 권한을 상속**합니다. 그러면 브라우저에 전달된 토큰이 API 키의 전체 접근 범위를 갖게 됩니다. 항상 명시적인 목록을 전달하세요.

작업은 발급하는 자격 증명 자체 권한의 부분집합이어야 합니다. API 키에 없는 권한은 부여할 수 없습니다.

현재 Whop 가이드 전반에 등장하는 작업은 다음과 같습니다:

| 작업 | 부여하는 권한 |
| - | - |
| `chat:read` | 채팅 채널과 메시지 읽기 |
| `chat:message:create` | 채팅 메시지 보내기 |
| `dms:read` | 다이렉트 메시지 읽기 |
| `dms:message:manage` | 다이렉트 메시지 보내기 및 관리 |
| `dms:channel:manage` | DM 채널 생성 및 관리 |
| `support_chat:read` | 지원 채팅 읽기 |
| `support_chat:message:create` | 지원 채팅 메시지 보내기 |
| `company:balance:read` | 계정 잔액 읽기 |

API는 고정된 목록을 게시하지 않으므로, 이를 전체 목록이 아니라 문서화된 집합으로 취급하세요. 권한의 최종 한계는 항상 발급하는 자격 증명 자체의 권한입니다.

## 계정 액세스 토큰

계정 액세스 토큰은 사용자 없이 계정 자체로 동작합니다. `POST /api/v1/access_tokens`에 `account_id`와 허용할 `scoped_actions`만 전달하여 생성합니다. 계정 범위 사용자 토큰과 같은 일정으로 만료됩니다.

임베드된 컴포넌트처럼 클라이언트가 짧은 시간 동안 계정의 접근 권한이 필요하고 특정 사용자가 관련되지 않을 때 사용하세요. 알림이나 환경설정 엔드포인트처럼 사용자로 동작하는 엔드포인트는 이 토큰을 거부합니다.

## `iframe` 사용자 토큰

앱이 Whop 안에서 렌더링되면 모든 동일 출처 요청은 `x-whop-user-token` 헤더에 수명이 짧은 JWT를 담고 있습니다. 서명을 검증해 누가 요청하는지 알아낸 다음, 무엇을 볼 수 있는지 확인하세요. Python과 Ruby SDK는 이를 위한 헬퍼를 제공합니다. TypeScript SDK는 제공하지 않으므로 JWT를 직접 검증하세요.

이 토큰은 직접 발급하지 않습니다. Whop이 전송하고 사용자가 검증합니다. [인증](https://docs.whop.com/ko/developer/guides/authentication.md)을 참고하세요.

## OAuth 토큰

OAuth 토큰은 Whop에 로그인해 일련의 범위에 대해 앱을 승인한 사용자를 나타냅니다. API 키와 달리, 접근 범위는 해당 개별 사용자가 할 수 있는 작업으로 제한됩니다.

Whop으로 로그인하기와, 사용자를 대신해 사용자 자신의 계정에서 작업할 때 사용하세요. [OAuth](https://docs.whop.com/ko/developer/guides/oauth.md)를 참고하세요.

## 범위 지정 체크리스트

자격 증명이 프로덕션에 도달하기 전에:

* 발급하는 모든 토큰에 명시적인 `scoped_actions`를 전달하세요. 상속에 절대 의존하지 마세요.
* 호출하는 엔드포인트를 파악했다면 API 키를 Admin으로 두지 말고 사용자 지정 권한 집합을 부여하세요.
* API 키는 서버 측에 보관하세요. 클라이언트에는 사용자 토큰만 둘 수 있습니다.
* 수명이 긴 토큰을 캐시하는 대신 수명이 짧은 토큰을 필요할 때 발급하세요.
* 환경마다 별도의 자격 증명을 사용하고, 돈이 오가는 작업을 실행하기 전에 어떤 자격 증명을 사용 중인지 확인하세요.

## 다음 단계

> [card] [빠른 시작](https://docs.whop.com/ko/developer/quickstart.md)
>
> 샌드박스 키를 만들고 첫 호출을 해 보세요.

> [card] [핵심 개념](https://docs.whop.com/ko/developer/concepts.md)
>
> 계정, 사용자, 권한이 어떻게 연결되는지 알아봅니다.

> [card] [OAuth](https://docs.whop.com/ko/developer/guides/oauth.md)
>
> 전체 OAuth 2.1 및 PKCE 흐름.

> [card] [샌드박스에서 테스트하기](https://docs.whop.com/ko/developer/guides/sandbox.md)
>
> 먼저 테스트 데이터로 자격 증명을 시험해 보세요.


## Related topics

- [KYC로 사용자 신원 인증하기](https://docs.whop.com/ko/developer/verification/overview.md)
- [채팅 인증](https://docs.whop.com/ko/developer/guides/chat/authentication.md)
- [Whop API 핵심 개념](https://docs.whop.com/ko/developer/concepts.md)
