---
title: OAuth 레퍼런스
url: https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference
description: 엔드포인트, 클라이언트 인증, 요청 매개변수, 스코프, 토큰 응답, 취소, 수명, 리디렉션 URI 규칙 및 오류를 다룹니다.
---

<Warning>
  Claude Platform OAuth는 Beta Service입니다. 이는 [상업 서비스 약관](https://www.anthropic.com/legal/commercial-terms) 및 [서비스별 약관](https://www.anthropic.com/legal/service-specific-terms) 등 Anthropic과의 계약에 따라 제공되는 출시 전 소프트웨어입니다. 베타 기간 동안 엔드포인트, 매개변수 및 동작이 변경될 수 있습니다. 프로덕션 환경에서 사용하기에 적합하지 않을 수 있습니다.
</Warning>

이 페이지는 [Claude Platform OAuth](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/overview)의 엔드포인트, 매개변수, 검증 규칙 및 오류 매핑을 정리한 것입니다. 단계별 안내는 [Linked billing](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections)을 참조하세요.

## 엔드포인트

| 엔드포인트                                                 | URL                                                                     |
| ----------------------------------------------------- | ----------------------------------------------------------------------- |
| Issuer(발급자)                                           | `https://identity.anthropic.com/users`                                  |
| Discovery document(디스커버리 문서)                          | `https://identity.anthropic.com/users/.well-known/openid-configuration` |
| 서명 키(JWKS)                                            | 디스커버리 문서의 `jwks_uri`로, `identity.anthropic.com`에서 호스팅됨                  |
| Authorization endpoint(인가 엔드포인트, 로그인 및 동의 페이지)        | `https://auth.claude.com/oauth/authorize`                               |
| “Pushed authorization request”(푸시 인가 요청), 즉 PAR 엔드포인트 | `https://auth.claude.com/v1/oauth/par`                                  |
| Token endpoint(토큰 엔드포인트)                              | `https://auth.claude.com/v1/oauth/token`                                |
| Revocation endpoint(취소 엔드포인트)                         | `https://auth.claude.com/v1/oauth/revoke`                               |
| Claude API (사용자 프로필 및 고객에게 청구되는 요청)                   | `https://api.anthropic.com`                                             |

서명 키는 하드코딩하지 말고 디스커버리 문서에서 읽어 오세요. 디스커버리 문서에는 PAR 엔드포인트와 취소 엔드포인트가 나열되어 있지 않으므로 이 표의 URL을 사용하세요.

## 디스커버리 문서 값

| 필드                                      | 값                                                |
| --------------------------------------- | ------------------------------------------------ |
| `issuer`                                | `https://identity.anthropic.com/users`           |
| `authorization_endpoint`                | `https://auth.claude.com/oauth/authorize`        |
| `token_endpoint`                        | `https://auth.claude.com/v1/oauth/token`         |
| `jwks_uri`                              | `https://identity.anthropic.com/users/jwks.json` |
| `response_types_supported`              | `code`                                           |
| `grant_types_supported`                 | `authorization_code`, `refresh_token`            |
| `code_challenge_methods_supported`      | `S256`                                           |
| `token_endpoint_auth_methods_supported` | `private_key_jwt`                                |
| `id_token_signing_alg_values_supported` | `ES256`                                          |
| `scopes_supported`                      | `openid`, `email`                                |
| `subject_types_supported`               | `public`, `pairwise`                             |

`auth.claude.com`은 고객이 `billing:attribution`과 함께 `offline_access`를 승인한 경우에만 Linked billing에 대해 refresh token(리프레시 토큰)을 반환합니다. [결제 연결의 OAuth 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)을 참조하세요.

## 클라이언트 인증

`auth.claude.com`은 `private_key_jwt` 방식([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523))으로 “confidential client”(기밀 클라이언트)를 인증합니다. PAR 엔드포인트, 토큰 엔드포인트 및 취소 엔드포인트에 보내는 모든 요청에 다음 매개변수를 포함하세요. 자격 증명을 URL 쿼리 문자열로 보내지 마세요. `auth.claude.com`은 이를 거부합니다.

| 매개변수                    | 값                                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`             | OAuth 앱의 클라이언트 ID                                                                                                                                 |
| `client_assertion_type` | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`                                                                                          |
| `client_assertion`      | [클라이언트 어설션 클레임](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#client-assertion-claims)의 클레임을 포함하는, ID 공급자가 발급한 JWT |

### 클라이언트 어설션 클레임

“Client assertion”(클라이언트 어설션)은 다음 클레임을 모두 포함해야 하며, 헤더에는 JWKS에 있는 키의 `kid`가 포함되어야 합니다.

| 클레임   | 요구 사항                                                                                                                                              |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss` | [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation)을 통해 등록한 것과 정확히 일치하는 ID 공급자의 발급자 URL |
| `sub` | 앱의 클라이언트 인증 설정에 subject 패턴을 지정한 경우, 해당 패턴과 일치하는 값                                                                                                  |
| `aud` | 정확히 하나의 audience: 앱의 클라이언트 인증 설정에 있는 값. `auth.claude.com`은 둘 이상의 audience를 나열한 어설션을 거부합니다.                                                         |
| `iat` | ID 공급자가 JWT를 발급한 시간                                                                                                                                |
| `exp` | 만료 시간으로, `iat` 이후 1시간을 넘지 않아야 합니다. 가능하면 더 짧은 수명을 사용하세요. 어설션을 가로챈 사람은 누구든 만료될 때까지 이를 사용할 수 있습니다.                                                    |

어설션 페이로드 예시:

```json
{
  "iss": "https://idp.example.com",
  "sub": "workload:prod:claude-integration-backend",
  "aud": "YOUR_CONFIGURED_AUDIENCE",
  "iat": 1791230000,
  "exp": 1791230300
}
```

subject 패턴과 클레임 조건은 백엔드가 허용하는 한 최대한 좁게 설정하세요. `auth.claude.com`은 이 조건과 일치하는 ID 공급자의 모든 JWT를 앱에 대한 인증으로 받아들입니다.

## 인가 요청 매개변수

`request_uri`를 제외한 이 매개변수는 푸시 인가 요청의 JSON 본문으로 보내세요.

| 매개변수                     | Linked billing | 설명                                                                                                                                                                          |
| ------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type`          | 필수             | 값 `code`                                                                                                                                                                    |
| `client_id`              | 필수             | OAuth 앱의 클라이언트 ID                                                                                                                                                           |
| `redirect_uri`           | 필수             | 등록된 리디렉션 URI와 정확히 일치하는 URI, 최대 2,048자                                                                                                                                       |
| `scope`                  | 필수             | 결제 연결의 경우 `billing:attribution` 또는 `billing:attribution offline_access`. [스코프](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#scopes)를 참조하세요. |
| `state`                  | 필수             | 콜백에서 확인하는 무작위 일회용 값, 최대 2,048자                                                                                                                                              |
| `code_challenge`         | 필수             | `BASE64URL(SHA256(code_verifier))`, 여기서 `code_verifier`는 43\~128자                                                                                                           |
| `code_challenge_method`  | 필수             | 값 `S256`                                                                                                                                                                    |
| `connection_type`        | 필수             | 값 `organization_shared`. 이 값은 결제를 위한 조직 연결을 요청합니다.                                                                                                                          |
| `connection_auth_target` | 필수             | 연결의 요청이 라우팅되는 조직. Linked billing의 경우 `platform`(OAuth 앱의 소유자)을 보내세요.                                                                                                        |
| `user_profile_id`        | 필수             | 고객을 나타내는, 조직 내 활성 사용자 프로필의 ID                                                                                                                                               |
| `request_uri`            | 필수             | PAR 엔드포인트가 반환한 값. `client_id`와 함께, 다른 매개변수 없이 인가 엔드포인트로 보내세요.                                                                                                               |

PAR 엔드포인트는 `request_uri` 및 `expires_in`(600초)과 함께 HTTP 201을 반환합니다.

## 스코프

| 범주 | 스코프                       | 설명                                                                                                                                                                                                                                                                 | 연결 유형                 | 클라이언트 유형 |
| -- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | -------- |
| 일반 | `offline_access`          | 요청된 다른 스코프를 나타내는 리프레시 토큰을 앱에 제공합니다. `organization_shared` 연결에서는 `billing:attribution`과 함께만 보내세요.                                                                                                                                                                   | `organization_shared` | 기밀       |
| 결제 | `billing:attribution`     | 고객의 지시에 따라 귀하가 보내는 Claude API 요청을 해당 고객의 Claude 조직에 청구할 수 있는 연결. 단독으로 보내거나, 리프레시 토큰도 받으려면 `offline_access`와 함께 보내세요. [결제 연결의 OAuth 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)을 참조하세요. | `organization_shared` | 기밀       |
| 결제 | `org:billing_attribution` | 지원 중단됨: `billing:attribution`을 사용하세요.                                                                                                                                                                                                                              | `organization_shared` | 기밀       |

## 토큰 요청 및 응답

토큰 요청은 JSON 본문과 함께 `https://auth.claude.com/v1/oauth/token`으로 보내세요.

| 매개변수                                                     | 값                                                                                                                  |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `grant_type`                                             | `authorization_code`                                                                                               |
| `code`                                                   | 콜백에서 받은 코드                                                                                                         |
| `redirect_uri`                                           | 인가 요청에서 보낸 것과 동일한 `redirect_uri`                                                                                   |
| `code_verifier`                                          | PKCE 코드 검증자                                                                                                        |
| `client_id`, `client_assertion_type`, `client_assertion` | [클라이언트 인증](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#client-authentication)과 동일 |

토큰 응답에는 다음 필드가 포함됩니다.

| 응답 필드                      | Linked billing                                                                                                                   |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`             | [연결의 액세스 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection) |
| `token_type`               | `Bearer`                                                                                                                         |
| `expires_in`               | 최대 `3600`                                                                                                                        |
| `scope`                    | `workspace:inference`                                                                                                            |
| `connection_id`            | 연결 ID, 예: `ocon_EXAMPLE`. 저장해 두세요.                                                                                               |
| `refresh_token`            | 고객이 `offline_access`를 승인한 경우에만 반환됨                                                                                               |
| `refresh_token_expires_in` | `refresh_token`이 만료될 때까지 남은 초. `refresh_token`이 없으면 포함되지 않음.                                                                     |

토큰을 갱신하려면 `grant_type`을 `refresh_token`으로 설정하고, `refresh_token`과 [클라이언트 인증](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#client-authentication)의 매개변수를 함께 보내세요. 결제 연결의 갱신은 [결제 연결의 OAuth 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)의 규칙을 따릅니다.

## 결제 연결의 OAuth 토큰

결제 연결의 경우 토큰 엔드포인트는 연결의 액세스 토큰을 반환합니다. 이 토큰은 앱의 `connection_token_workspace_id` 설정에 지정된 워크스페이스에서 앱의 [operator service account(운영자 서비스 계정)](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#terms)으로 인증됩니다. `/v1/messages` 및 `/v1/chat/completions`에서 이 토큰을 사용한 요청은 해당 연결의 고객에게만 청구되며 다른 누구에게도 청구되지 않습니다. 고객이 `offline_access`도 승인한 경우 토큰 엔드포인트는 리프레시 토큰도 반환하며, `refresh_token` 그랜트는 두 토큰을 모두 갱신합니다. 설정 및 단계별 안내는 Linked billing 페이지의 [연결별 OAuth 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)을 참조하세요.

두 그랜트 모두 [클라이언트 인증](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#client-authentication)과 함께 [토큰 요청 및 응답](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#token-request-and-response)의 매개변수를 사용합니다. 갱신 시에는 `scope` 매개변수를 보내면 안 됩니다. 토큰 응답에는 다음 필드가 포함됩니다.

| 응답 필드                      | 값                                                             |
| -------------------------- | ------------------------------------------------------------- |
| `access_token`             | 연결의 액세스 토큰                                                    |
| `token_type`               | `Bearer`                                                      |
| `expires_in`               | 액세스 토큰이 만료될 때까지 남은 초, 최대 `3600`                               |
| `scope`                    | 항상 `workspace:inference`                                      |
| `connection_id`            | 연결 ID, 예: `ocon_EXAMPLE`. `authorization_code` 그랜트만 이를 반환합니다. |
| `refresh_token`            | 연결의 리프레시 토큰. 고객이 `offline_access`를 승인한 경우에만 반환됩니다.            |
| `refresh_token_expires_in` | `refresh_token`이 만료될 때까지 남은 초                                 |

각 갱신은 새 `access_token`과 새 `refresh_token`을 반환합니다. 보낸 리프레시 토큰은 대체되며, 이전 액세스 토큰은 몇 분 이내에 작동을 멈춥니다. 응답을 받지 못한 요청을 반복하기 위해, 대체된 리프레시 토큰을 해당 토큰을 대체한 갱신 후 30초 이내에 한 번 더 보낼 수 있습니다. 이 두 번째 요청은 또 다른 새 토큰 쌍을 반환하고 받지 못한 응답의 토큰 쌍을 취소하므로, 가장 최근의 토큰 쌍만 사용하세요. 대체된 토큰을 사용한 세 번째 요청은 `invalid_grant`를 받으며, 30초가 지난 후에 도착한 두 번째 요청도 마찬가지입니다. 30초 이내에는 이러한 요청이 아무것도 취소하지 않습니다. 30초가 지난 후에는 이러한 요청이 연결의 모든 토큰을 취소하고 연결을 종료합니다. [토큰 갱신](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)에서 갱신의 규칙과 오류를 확인할 수 있습니다.

다음 각 이벤트는 현재 액세스 토큰을 포함하여 연결의 토큰을 취소합니다.

* 고객 또는 귀하가 연결을 해제합니다.
* 고객이 같은 사용자 프로필에 대해 다른 스코프로 새 인가 요청을 승인하고, 귀하가 해당 승인의 코드를 교환합니다. 새 연결이 이전 연결을 대체합니다.
* 토큰이 실행되는 워크스페이스가 보관됩니다.

Claude API가 연결의 액세스 토큰을 사용한 요청에 어떻게 청구하는지는 [연결의 액세스 토큰으로 Claude 호출](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)을 참조하세요.

## 취소

“Revocation”(취소) 요청은 JSON 또는 폼 인코딩된 본문과 함께 `https://auth.claude.com/v1/oauth/revoke`로 보내세요. 이 엔드포인트는 [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)를 따르며, 연결 ID와 사용자 프로필 ID도 받습니다.

[클라이언트 인증](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#client-authentication)의 매개변수와 함께 이 표의 매개변수 중 정확히 하나를 보내세요. 클라이언트 어설션의 `aud`는 취소 URL이 아니라 앱의 클라이언트 인증 설정에 있는 값입니다.

| 매개변수              | 종료 대상                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `connection_id`   | 앱의 연결 중 하나로, `ocon_` ID로 지정합니다                                                                    |
| `user_profile_id` | 한 사용자 프로필에 있는 앱의 모든 연결로, `uprof_` ID로 지정합니다                                                       |
| `token`           | Linked billing의 경우 대신 `connection_id` 또는 `user_profile_id`를 보내세요. 액세스 토큰을 보내면 연결이 종료되지 않을 수 있습니다. |

`auth.claude.com`은 `token_type_hint`를 받지만 무시합니다.

엔드포인트는 HTTP 200과 함께 요청이 종료한 연결의 ID를 반환합니다.

```json
{
  "revoked_connection_ids": ["ocon_EXAMPLE"]
}
```

토큰이나 ID를 알 수 없거나 다른 앱에 속한 경우, 연결이 이미 종료된 경우, 또는 요청이 토큰은 종료했지만 연결은 종료하지 않은 경우 목록은 비어 있습니다. 응답에는 어느 경우인지 표시되지 않습니다.

결제 연결이 종료된 후 Claude API는 해당 고객에게 청구하는 요청을 `user_profile_not_billable`로 거부하며, 연결의 OAuth 토큰은 작동을 멈춥니다. 그 이후에는 지원 중단된 `org:billing_attribution` 스코프로 승인된 연결의 액세스 토큰에 의존하지 마세요. 즉시 작동을 멈출 수도 있고, 만료될 때까지 작동할 수도 있습니다.

## 수명

| 항목                       | 수명                                |
| ------------------------ | --------------------------------- |
| PAR 엔드포인트의 `request_uri` | 10분, 일회용                          |
| 인가 코드                    | 5분, 일회용                           |
| `access_token`           | 최대 1시간                            |
| `refresh_token`          | 코드 교환 시점부터 최대 1년. 갱신해도 연장되지 않습니다. |

이는 현재 값입니다. 고정된 값에 의존하지 말고 각 응답에서 `expires_in`과 `refresh_token_expires_in`을 읽으세요.

## 리디렉션 URI 규칙

* 각 `redirect_uri`는 앱에 등록된 URI와 정확히 일치해야 합니다. `auth.claude.com`은 와일드카드나 접두사 일치를 사용하지 않습니다.
* 모든 리디렉션 URI는 HTTPS를 사용해야 하며 프래그먼트를 포함해서는 안 됩니다. `localhost`, `127.0.0.1` 또는 `[::1]`의 로컬 개발용 URI는 HTTP를 사용할 수 있습니다.
* `http://localhost:*/callback`처럼 포트에 별표를 사용하여 등록한 로컬 개발용 URI는 모든 포트와 일치합니다.
* 앱마다 최대 10개의 리디렉션 URI를 등록할 수 있습니다.
* `auth.claude.com`은 `redirect_uri`가 등록된 URI와 일치하는 경우에만 리디렉션 URI로 오류를 보냅니다. 그 외의 `redirect_uri`에 대해서는 `auth.claude.com`이 브라우저를 리디렉션하지 않습니다.

## 오류

### 리디렉션 시 오류

`auth.claude.com`은 리디렉션 URI의 `error`, `error_description`, `state` 쿼리 매개변수로 오류를 반환합니다. 이는 Anthropic 고유의 `user_profile_already_linked`를 제외하면 표준 OAuth 2.0 오류([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749))입니다.

| 오류                            | 발생 시점                                                                                                                                      | 사용자에게 표시할 내용                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `access_denied`               | 사용자가 거부했거나, 이 요청을 승인할 수 없습니다. 결제 연결의 경우 해당 사용자는 Claude 조직의 관리자여야 합니다.                                                                      | 연결이 완료되지 않았음을 설명하고, 사용자가 거부했다고 가정하지 마세요. 결제 연결의 경우 Linked billing 가이드의 [리디렉션 URI가 `error=access_denied`를 받는 경우](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#access-denied)를 따르세요. 이 항목에 원인과 사용자에게 안내할 내용이 나와 있습니다. 그 외의 경우에는 사용자에게 귀하에게 연락하도록 요청하세요. |
| `server_error`                | `auth.claude.com`이 요청을 처리하지 못했습니다.                                                                                                         | 사용자에게 다시 시도하도록 요청하세요.                                                                                                                                                                                                                                                                                  |
| `user_profile_already_linked` | Linked billing에만 해당. 고객의 조직이 이미 다른 사용자 프로필을 통해 앱에 연결되어 있습니다. 각 고객 조직은 앱과 하나의 연결만 가질 수 있습니다. `auth.claude.com`은 이미 관리자에게 귀하에게 연락하도록 요청했습니다. | 해당 조직이 이미 앱에 연결되어 있음을 설명하세요.                                                                                                                                                                                                                                                                           |

`request_uri`가 만료되었거나 이미 사용한 경우, `auth.claude.com`이 오류 페이지를 표시하며 브라우저를 앱으로 다시 리디렉션하지 않습니다. 새로운 푸시 인가 요청으로 흐름을 다시 시작하세요.

### PAR 및 토큰 엔드포인트의 오류

이 엔드포인트는 `error`와 `error_description`이 포함된 JSON 본문을 반환합니다.

| 오류                            | 발생 시점                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`             | 필수 매개변수가 누락되었거나 유효하지 않습니다. 예를 들어 `state`나 PKCE 챌린지가 누락되었거나, `user_profile_id`가 조직 내 활성 사용자 프로필의 ID가 아닌 경우입니다.                                                                                                                                                                                                                                                                                                                                                                                         |
| `invalid_client`              | `auth.claude.com`이 앱을 인증할 수 없습니다. 클라이언트 ID를 알 수 없거나 클라이언트 어설션 검증에 실패했습니다. 어설션의 `iss`, `sub`, `aud`를 앱의 클라이언트 인증 설정과 대조하고, ID 공급자가 JWKS에 있는 키로 서명했는지 확인하세요.                                                                                                                                                                                                                                                                                                                                            |
| `invalid_scope`               | 요청한 스코프가 이 앱 또는 이 연결 유형에 허용되지 않습니다. [결제 연결의 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)의 경우, 갱신 시 허용되지 않는 `scope` 매개변수를 보냈거나 앱에 `billing:attribution`이 더 이상 등록되어 있지 않다는 의미이기도 합니다. 코드 교환 시에는 두 번째 원인으로 인해 코드가 소모됩니다.                                                                                                                                                                                                      |
| `invalid_grant`               | 코드가 만료되었거나, 이미 사용했거나, `redirect_uri` 또는 `code_verifier`와 일치하지 않습니다. 갱신의 경우 리프레시 토큰이 만료되었거나 더 이상 유효하지 않으므로, [토큰 갱신](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)의 안내를 따르세요.                                                                                                                                                                                                                                                   |
| `unauthorized_client`         | 앱이 이 요청에 맞게 설정되어 있지 않습니다. Linked billing의 경우 먼저 앱의 운영자 서비스 계정과 해당 워크스페이스를 확인하세요. [코드 교환이 `unauthorized_client`를 반환하는 경우](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client)를 참조하세요. [결제 연결의 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)의 경우 `error_description`에 원인이 표시됩니다. 예를 들어 워크스페이스가 누락된 경우입니다. 이 거부는 코드를 소모하지 않으며 리프레시 토큰을 취소하지 않습니다. |
| `user_profile_already_linked` | Linked billing에만 해당하며, 토큰 엔드포인트에서 반환됩니다. 승인과 이 요청 사이에 사용자 프로필이 다른 고객 조직을 통해 앱에 연결되었거나, 고객의 조직이 다른 사용자 프로필을 통해 연결되었습니다.                                                                                                                                                                                                                                                                                                                                                                                |

`auth.claude.com`이 요청에 “rate limit”(속도 제한)을 적용하거나, 장애가 발생하거나, 알 수 없는 `grant_type` 또는 길이 제한을 초과하는 매개변수를 받으면 다른 형식의 오류를 반환하며, 이는 JSON이 아닐 수 있습니다. HTTP 429 및 5xx 응답에 대해서만 백오프를 적용하여 재시도하세요. 그 외의 상태는 요청 자체의 결함으로 취급하세요. 결제 연결의 갱신에 대해서는 일반적인 백오프 대신 [토큰 갱신](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)의 안내를 따르세요. 응답에 `retry-after` 헤더가 있으면 최소한 그 시간만큼 기다리세요. 다음 요청은 직접 작성한 코드에서 보내고, HTTP 클라이언트 라이브러리의 자동 재시도에 의존하지 마세요. 이러한 응답에 대해서는 자동 재시도가 실행되지 않을 수 있습니다. [토큰 갱신](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)에서는 재시도가 안전한 시점도 안내합니다. 이미 사용된 리프레시 토큰을 다시 보내면 연결이 종료될 수 있기 때문입니다.

### 취소 엔드포인트의 오류

`auth.claude.com`이 거부하는 대부분의 요청에 대해 취소 엔드포인트는 HTTP 400과 함께 `error`와 `error_description`이 포함된 JSON 본문을 반환합니다.

| 오류                    | 발생 시점                                                                                                                                                                                                                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`     | 필수 매개변수가 누락되었거나 유효하지 않습니다. 예를 들어 `client_id`가 누락된 경우입니다. 요청이 `token`, `connection_id`, `user_profile_id` 중 어느 것도 보내지 않았거나 둘 이상을 보냈습니다. ID 형식이 잘못되었습니다. 예를 들어 접두사가 잘못된 경우입니다. 자격 증명이나 `token`이 URL 쿼리 문자열에 있습니다. 사용자 프로필에 한 번의 요청으로 처리하기에는 너무 많은 연결이 있습니다. 요청이 그중 일부를 종료했을 수 있으므로, 나머지는 `connection_id`로 종료하세요. |
| `invalid_client`      | `auth.claude.com`이 앱을 인증할 수 없습니다. 확인할 사항은 [PAR 및 토큰 엔드포인트의 오류](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#errors-from-the-par-and-token-endpoints)의 `invalid_client`를 참조하세요.                                                                                                 |
| `unauthorized_client` | 앱이 이 요청에 맞게 설정되어 있지 않습니다. Anthropic 계정 팀에 문의하세요.                                                                                                                                                                                                                                                               |

다음 표의 응답은 다른 형식을 사용하며, JSON이 아닐 수 있습니다. 본문이 JSON인 경우 `error`는 문자열이 아닌 객체입니다.

| 상태  | 발생 시점                                      | 수행할 작업                                                                                                                                                                                                                            |
| --- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | 매개변수가 길이 제한을 초과합니다.                        | 요청을 수정하세요. 재시도하지 마세요.                                                                                                                                                                                                             |
| 429 | IP 주소에서 실패한 요청이 너무 많이 발생했습니다.              | 백오프를 적용하여 재시도하세요.                                                                                                                                                                                                                 |
| 500 | `auth.claude.com`이 요청을 처리하지 못했습니다.         | 백오프를 적용하여 재시도하세요. 계속 발생하면 Anthropic 계정 팀에 문의하세요.                                                                                                                                                                                  |
| 501 | Anthropic이 귀하의 조직에 이 엔드포인트를 활성화하지 않았습니다.   | 재시도하지 마세요. Anthropic 계정 팀에 문의하세요.                                                                                                                                                                                                 |
| 503 | 요청이 완료되지 않았습니다. 요청이 종료한 항목은 종료된 상태로 유지됩니다. | 동일한 매개변수와 새 클라이언트 어설션으로 백오프를 적용하여 재시도하세요. 재시도가 나머지를 완료하며, 재시도의 목록에는 이전 요청이 종료한 연결이 포함되지 않습니다. `user_profile_id`를 보낸 경우 하루 이내에 재시도하세요. 그 이후에는 재시도가 빈 목록과 함께 200을 반환하고 아무것도 완료하지 않을 수 있습니다. 각 `connection_id`를 사용한 재시도는 언제든지 작동합니다. |

### 결제 오류

이 오류는 `billing_policy.bill_to`를 `"user_profile"`로 설정하거나 [결제 연결의 액세스 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)으로 인증하는 Claude API 요청에 적용됩니다. Claude API는 거부된 요청에 대해 어느 조직에도 비용을 청구하지 않습니다. 새 연결 후 처음 10초 이내의 `user_profile_not_billable` 거부를 제외하면, 402 및 403 응답은 모두 재시도할 수 없습니다.

| 상태  | 오류 유형 및 코드                                                 | 발생 시점                                                                                                                                                                                                                                                                                                                                                                                                            |
| --- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `invalid_request_error`                                    | 요청이 `user-profiles-billing-2026-10-01` 베타 헤더 없이 `billing_policy`를 보냈습니다. 또는 `billing_policy` 객체에 누락되었거나 유효하지 않은 필드가 있습니다. 결제 연결의 액세스 토큰을 사용하는 경우 `bill_to`는 생략할 수 있습니다. 또는 요청이 허용된 조합 외에서 코드 실행을 사용했습니다.                                                                                                                                                                                                         |
| 400 | `invalid_request_error`, `user_profile_required`           | `bill_to`가 `"user_profile"`이고, 요청에 사용자 프로필 ID가 포함되어 있지 않으며, 결제 연결의 액세스 토큰으로 인증하지도 않습니다.                                                                                                                                                                                                                                                                                                                          |
| 400 | `invalid_request_error`, 오류 코드 없음                          | 요청이 결제 연결의 액세스 토큰으로 인증하면서 `bill_to`를 `"self"`로 설정했거나, 토큰이 제한된 사용자 프로필이 아닌 다른 사용자 프로필을 지정했습니다. 이 두 거부는 각각 `error.message`에 무엇이 잘못되었는지 표시합니다.                                                                                                                                                                                                                                                                      |
| 401 | `authentication_error`                                     | 요청이 만료되었거나, 갱신으로 대체되었거나, 연결이 종료된 결제 연결의 액세스 토큰으로 인증합니다. 메시지에는 토큰이 만료되었는지 취소되었는지가 표시됩니다. 현재 액세스 토큰으로 요청을 다시 보내거나, 연결이 종료된 경우 고객을 다시 연결하세요. 연결이 종료된 후에는 해당 액세스 토큰을 사용한 각 새 요청이 정해진 순서 없이 이 401 또는 403 `user_profile_not_billable`을 받을 수 있습니다.                                                                                                                                                                      |
| 402 | `billing_error`, `linked_organization_spend_limit_reached` | 고객 조직이 귀하의 OAuth 앱 또는 자체 조직 전체에 대해 설정한 지출 제한에 도달했습니다. 조직에 요청 비용을 지불할 수 있는 크레딧이 없는 경우에도 동일한 코드가 전송됩니다. 응답에는 어느 쪽인지 표시되지 않습니다. 고객에게 두 제한과 크레딧 잔액을 모두 확인하도록 요청하세요. Linked billing의 [예상되는 오류](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#expected-errors)에서 각 항목을 설정하는 위치와 변경할 사항을 확인할 수 있습니다.                                                                    |
| 402 | `billing_error`, `linked_organization_billing_unavailable` | 고객 조직 자체의 Anthropic 계정에 문제가 있기 때문에 Anthropic이 현재 해당 조직에 청구할 수 없습니다. 조직의 크레딧이 소진되면 Claude가 이미 시작한 응답도 동일한 코드로 종료됩니다. 고객에게 Anthropic에서 결제 상태를 확인하도록 요청하세요.                                                                                                                                                                                                                                                         |
| 403 | `permission_error`, 오류 코드 없음                               | Anthropic이 귀하의 조직에 직접 청구하지 않으므로, 귀하를 대신하여 고객에게 청구할 수 없습니다.                                                                                                                                                                                                                                                                                                                                                       |
| 403 | `permission_error`, `user_profile_not_billable`            | 사용자 프로필이 고객 조직과 연결되어 있지 않거나, 관리자 또는 백엔드가 연결을 종료했거나, 고객 조직이 API 사용량에 대해 Anthropic에 직접 비용을 지불하지 않거나(선불 크레딧과 인보이스 결제는 모두 직접 지불로 간주됨), 요청이 앱의 서비스 계정으로 인증되지 않았습니다. 응답에는 어느 쪽인지 표시되지 않습니다. 연결이 종료된 후에는 연결의 액세스 토큰도 이 오류를 받을 수 있습니다. [`user_profile_not_billable`의 원인](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)에서 각 경우에 확인할 사항을 안내합니다. |
| 503 | `overloaded_error`                                         | Claude API가 일시적으로 고객에게 청구할 수 있는지 확인할 수 없습니다. 요청을 재시도하세요. 응답에 `retry-after` 헤더가 포함된 경우, 재시도하기 전에 해당 시간만큼 기다리세요.                                                                                                                                                                                                                                                                                                   |

`/v1/messages`에서는 오류 코드가 `error.details.error_code`에 있습니다. `/v1/chat/completions`에서는 `error.type`이 항상 `invalid_request_error`이고, `error.code`에 Anthropic 오류 유형(예: `permission_error` 또는 `billing_error`)이 포함되며, 응답에 오류 코드가 없으므로 HTTP 상태와 `error.code`로 판별하세요.

## 표준

| 표준                                                               | 적용 대상                                                                               |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [OAuth 2.0 (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749)   | 인가 코드 흐름, 토큰 엔드포인트 및 오류 응답                                                          |
| [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)        | 모든 인가 요청에서 `S256`과 함께 필수                                                            |
| [푸시 인가 요청(RFC 9126)](https://www.rfc-editor.org/rfc/rfc9126)     | Linked billing에서는 필수.                                                               |
| [토큰 취소(RFC 7009)](https://www.rfc-editor.org/rfc/rfc7009)        | 연결 ID와 사용자 프로필 ID도 받으며, 종료한 연결의 ID를 반환하는 취소 엔드포인트                                   |
| [JWT 클라이언트 인증(RFC 7523)](https://www.rfc-editor.org/rfc/rfc7523) | PAR, 토큰 및 취소 엔드포인트에서의 `private_key_jwt` 클라이언트 인증, 그리고 고객에게 청구되는 요청을 위한 서비스 계정 토큰 교환 |

## 이 페이지들에서 사용하는 용어

다음 의미는 Claude Platform OAuth에만 적용됩니다.

| 용어                           | 의미                                                                                                                                                                                                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Claude 조직                    | Anthropic의 조직 계정. 귀하의 회사에도 하나가 있고, 결제를 위해 조직을 연결하는 각 고객에게도 하나씩 있습니다.                                                                                                                                                                                                                       |
| 관리자                          | 관리자 또는 결제 역할을 가진 Claude 조직의 구성원.                                                                                                                                                                                                                                                           |
| OAuth 앱                      | Claude 조직에 등록된 항목으로, `auth.claude.com`에 제품을 식별시킵니다. 클라이언트 ID, 이름, 로고, 홈페이지 URL, 리디렉션 URI, 지원하는 연결 유형을 가집니다.                                                                                                                                                                                |
| 연결 유형                        | 연결을 승인하는 주체: 조직 전체를 대신하는 관리자(`organization_shared`, Linked billing용).                                                                                                                                                                                                                      |
| ID 공급자                       | 백엔드를 위해 수명이 짧은 JWT에 서명하고 공개 키를 JSON Web Key Set(JWKS)으로 게시하는, 귀하의 자체 인프라에 있는 서비스. 예를 들어 클라우드 공급자의 워크로드 ID 서비스나 자체 OIDC 호환 발급자가 있습니다. 이 페이지들에서 “ID 공급자”는 항상 Anthropic이 아닌 이 서비스를 의미합니다.                                                                                                     |
| 클라이언트 어설션                    | ID 공급자가 서명하고 백엔드가 OAuth 앱을 인증하기 위해 보내는, 수명이 짧은 JWT. 이는 `private_key_jwt` 클라이언트 인증 방식(RFC 7523)입니다.                                                                                                                                                                                         |
| 푸시 인가 요청(PAR)                | 백엔드가 인가 매개변수를 `auth.claude.com`에 직접 보내고, 브라우저 리디렉션에 사용할 `request_uri`를 받는 요청(RFC 9126).                                                                                                                                                                                                    |
| Workload Identity Federation | 조직이 ID 공급자를 등록하여 Anthropic이 JWKS의 키로 서명된 JWT를 받아들이도록 하는 Claude Console 기능.                                                                                                                                                                                                                 |
| 디스커버리 문서                     | Anthropic의 발급자, 엔드포인트 및 서명 키를 나열하는 OIDC 문서.                                                                                                                                                                                                                                                |
| 사용자 프로필                      | 고객 한 명을 나타내기 위해 귀하의 Claude 조직에 생성하는 레코드. 결제 연결은 사용자 프로필을 고객의 Claude 조직에 연결합니다.                                                                                                                                                                                                             |
| 서비스 계정                       | Claude 조직 내의 사람이 아닌 계정. Linked billing의 경우 OAuth 앱은 하나의 서비스 계정, 즉 운영자 서비스 계정에 연결되며, 백엔드는 고객에게 청구되는 요청을 보낼 때 해당 서비스 계정으로 인증합니다.                                                                                                                                                             |
| 연결의 OAuth 토큰                 | 결제 연결에 대해 `auth.claude.com`이 반환하는 액세스 토큰과, 고객이 `offline_access`도 승인한 경우 반환하는 리프레시 토큰. 액세스 토큰은 운영자 서비스 계정으로 인증되며 해당 연결의 사용자 프로필에만 청구할 수 있습니다. [결제 연결의 OAuth 토큰](https://platform.claude.com/docs/ko/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)을 참조하세요. |
