OAuth 레퍼런스
엔드포인트, 클라이언트 인증, 요청 매개변수, 스코프, 토큰 응답, 취소, 수명, 리디렉션 URI 규칙 및 오류를 다룹니다.
이 페이지는 Claude Platform OAuth의 엔드포인트, 매개변수, 검증 규칙 및 오류 매핑을 정리한 것입니다. 단계별 안내는 Linked billing을 참조하세요.
엔드포인트
| 엔드포인트 | 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 토큰을 참조하세요.
클라이언트 인증
auth.claude.com은 private_key_jwt 방식(RFC 7523)으로 “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 | 클라이언트 어설션 클레임의 클레임을 포함하는, ID 공급자가 발급한 JWT |
클라이언트 어설션 클레임
“Client assertion”(클라이언트 어설션)은 다음 클레임을 모두 포함해야 하며, 헤더에는 JWKS에 있는 키의 kid가 포함되어야 합니다.
| 클레임 | 요구 사항 |
|---|---|
iss | Workload Identity Federation을 통해 등록한 것과 정확히 일치하는 ID 공급자의 발급자 URL |
sub | 앱의 클라이언트 인증 설정에 subject 패턴을 지정한 경우, 해당 패턴과 일치하는 값 |
aud | 정확히 하나의 audience: 앱의 클라이언트 인증 설정에 있는 값. auth.claude.com은 둘 이상의 audience를 나열한 어설션을 거부합니다. |
iat | ID 공급자가 JWT를 발급한 시간 |
exp | 만료 시간으로, iat 이후 1시간을 넘지 않아야 합니다. 가능하면 더 짧은 수명을 사용하세요. 어설션을 가로챈 사람은 누구든 만료될 때까지 이를 사용할 수 있습니다. |
어설션 페이로드 예시:
{
"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. 스코프를 참조하세요. |
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 토큰을 참조하세요. | 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 | 클라이언트 인증과 동일 |
토큰 응답에는 다음 필드가 포함됩니다.
| 응답 필드 | Linked billing |
|---|---|
access_token | 연결의 액세스 토큰 |
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과 클라이언트 인증의 매개변수를 함께 보내세요. 결제 연결의 갱신은 결제 연결의 OAuth 토큰의 규칙을 따릅니다.
결제 연결의 OAuth 토큰
결제 연결의 경우 토큰 엔드포인트는 연결의 액세스 토큰을 반환합니다. 이 토큰은 앱의 connection_token_workspace_id 설정에 지정된 워크스페이스에서 앱의 operator service account(운영자 서비스 계정)으로 인증됩니다. /v1/messages 및 /v1/chat/completions에서 이 토큰을 사용한 요청은 해당 연결의 고객에게만 청구되며 다른 누구에게도 청구되지 않습니다. 고객이 offline_access도 승인한 경우 토큰 엔드포인트는 리프레시 토큰도 반환하며, refresh_token 그랜트는 두 토큰을 모두 갱신합니다. 설정 및 단계별 안내는 Linked billing 페이지의 연결별 OAuth 토큰을 참조하세요.
두 그랜트 모두 클라이언트 인증과 함께 토큰 요청 및 응답의 매개변수를 사용합니다. 갱신 시에는 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초가 지난 후에는 이러한 요청이 연결의 모든 토큰을 취소하고 연결을 종료합니다. 토큰 갱신에서 갱신의 규칙과 오류를 확인할 수 있습니다.
다음 각 이벤트는 현재 액세스 토큰을 포함하여 연결의 토큰을 취소합니다.
- 고객 또는 귀하가 연결을 해제합니다.
- 고객이 같은 사용자 프로필에 대해 다른 스코프로 새 인가 요청을 승인하고, 귀하가 해당 승인의 코드를 교환합니다. 새 연결이 이전 연결을 대체합니다.
- 토큰이 실행되는 워크스페이스가 보관됩니다.
Claude API가 연결의 액세스 토큰을 사용한 요청에 어떻게 청구하는지는 연결의 액세스 토큰으로 Claude 호출을 참조하세요.
취소
“Revocation”(취소) 요청은 JSON 또는 폼 인코딩된 본문과 함께 https://auth.claude.com/v1/oauth/revoke로 보내세요. 이 엔드포인트는 RFC 7009를 따르며, 연결 ID와 사용자 프로필 ID도 받습니다.
클라이언트 인증의 매개변수와 함께 이 표의 매개변수 중 정확히 하나를 보내세요. 클라이언트 어설션의 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를 반환합니다.
{
"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)입니다.
| 오류 | 발생 시점 | 사용자에게 표시할 내용 |
|---|---|---|
access_denied | 사용자가 거부했거나, 이 요청을 승인할 수 없습니다. 결제 연결의 경우 해당 사용자는 Claude 조직의 관리자여야 합니다. | 연결이 완료되지 않았음을 설명하고, 사용자가 거부했다고 가정하지 마세요. 결제 연결의 경우 Linked billing 가이드의 리디렉션 URI가 error=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 | 요청한 스코프가 이 앱 또는 이 연결 유형에 허용되지 않습니다. 결제 연결의 토큰의 경우, 갱신 시 허용되지 않는 scope 매개변수를 보냈거나 앱에 billing:attribution이 더 이상 등록되어 있지 않다는 의미이기도 합니다. 코드 교환 시에는 두 번째 원인으로 인해 코드가 소모됩니다. |
invalid_grant | 코드가 만료되었거나, 이미 사용했거나, redirect_uri 또는 code_verifier와 일치하지 않습니다. 갱신의 경우 리프레시 토큰이 만료되었거나 더 이상 유효하지 않으므로, 토큰 갱신의 안내를 따르세요. |
unauthorized_client | 앱이 이 요청에 맞게 설정되어 있지 않습니다. Linked billing의 경우 먼저 앱의 운영자 서비스 계정과 해당 워크스페이스를 확인하세요. 코드 교환이 unauthorized_client를 반환하는 경우를 참조하세요. 결제 연결의 토큰의 경우 error_description에 원인이 표시됩니다. 예를 들어 워크스페이스가 누락된 경우입니다. 이 거부는 코드를 소모하지 않으며 리프레시 토큰을 취소하지 않습니다. |
user_profile_already_linked | Linked billing에만 해당하며, 토큰 엔드포인트에서 반환됩니다. 승인과 이 요청 사이에 사용자 프로필이 다른 고객 조직을 통해 앱에 연결되었거나, 고객의 조직이 다른 사용자 프로필을 통해 연결되었습니다. |
auth.claude.com이 요청에 “rate limit”(속도 제한)을 적용하거나, 장애가 발생하거나, 알 수 없는 grant_type 또는 길이 제한을 초과하는 매개변수를 받으면 다른 형식의 오류를 반환하며, 이는 JSON이 아닐 수 있습니다. HTTP 429 및 5xx 응답에 대해서만 백오프를 적용하여 재시도하세요. 그 외의 상태는 요청 자체의 결함으로 취급하세요. 결제 연결의 갱신에 대해서는 일반적인 백오프 대신 토큰 갱신의 안내를 따르세요. 응답에 retry-after 헤더가 있으면 최소한 그 시간만큼 기다리세요. 다음 요청은 직접 작성한 코드에서 보내고, HTTP 클라이언트 라이브러리의 자동 재시도에 의존하지 마세요. 이러한 응답에 대해서는 자동 재시도가 실행되지 않을 수 있습니다. 토큰 갱신에서는 재시도가 안전한 시점도 안내합니다. 이미 사용된 리프레시 토큰을 다시 보내면 연결이 종료될 수 있기 때문입니다.
취소 엔드포인트의 오류
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 및 토큰 엔드포인트의 오류의 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"로 설정하거나 결제 연결의 액세스 토큰으로 인증하는 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의 예상되는 오류에서 각 항목을 설정하는 위치와 변경할 사항을 확인할 수 있습니다. |
| 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의 원인에서 각 경우에 확인할 사항을 안내합니다. |
| 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) | 인가 코드 흐름, 토큰 엔드포인트 및 오류 응답 |
| PKCE (RFC 7636) | 모든 인가 요청에서 S256과 함께 필수 |
| 푸시 인가 요청(RFC 9126) | Linked billing에서는 필수. |
| 토큰 취소(RFC 7009) | 연결 ID와 사용자 프로필 ID도 받으며, 종료한 연결의 ID를 반환하는 취소 엔드포인트 |
| JWT 클라이언트 인증(RFC 7523) | 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 토큰을 참조하세요. |
이 페이지가 도움이 되었나요?