OAuth 參考
端點、用戶端驗證、請求參數、範圍、權杖回應、撤銷、有效期限、重新導向 URI 規則以及錯誤。
此頁面彙整了 Claude Platform OAuth 的端點、參數、驗證規則和錯誤對應。如需逐步說明,請參閱 Linked billing。
端點
| 端點 | URL |
|---|---|
| 簽發者(Issuer) | https://identity.anthropic.com/users |
| 探索文件 | https://identity.anthropic.com/users/.well-known/openid-configuration |
| 簽署金鑰(JWKS) | 探索文件中的 jwks_uri,託管於 identity.anthropic.com |
| 授權端點(登入與同意頁面) | https://auth.claude.com/oauth/authorize |
| 推送授權請求(PAR)端點 | https://auth.claude.com/v1/oauth/par |
| 權杖端點 | https://auth.claude.com/v1/oauth/token |
| 撤銷端點 | 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 |
只有在客戶同時核准 offline_access 與 billing:attribution 時,auth.claude.com 才會為 Linked billing 傳回重新整理權杖:請參閱計費連線的 OAuth 權杖。
用戶端驗證
auth.claude.com 使用 private_key_jwt 方法(RFC 7523)驗證機密用戶端。請在每個傳送至 PAR 端點、權杖端點和撤銷端點的請求中傳送這些參數。切勿在 URL 查詢字串中傳送憑證:auth.claude.com 會拒絕它們。
| 參數 | 值 |
|---|---|
client_id | 您的 OAuth 應用程式的用戶端 ID |
client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
client_assertion | 來自您身分識別提供者的 JWT,包含用戶端斷言宣告中的宣告 |
用戶端斷言宣告
「Client assertion」(用戶端斷言)必須包含以下所有宣告,且其標頭必須包含您 JWKS 中某個金鑰的 kid。
| 宣告 | 要求 |
|---|---|
iss | 您身分識別提供者的簽發者 URL,必須與透過工作負載身分聯合註冊的完全相同 |
sub | 若您有設定主體模式,則為符合您應用程式用戶端驗證設定中主體模式的值 |
aud | 恰好一個受眾:即您應用程式用戶端驗證設定中的值。auth.claude.com 會拒絕列出多個受眾的斷言。 |
iat | 您的身分識別提供者簽發 JWT 的時間 |
exp | 到期時間,不得晚於 iat 之後 1 小時。請盡可能使用較短的有效期限:任何攔截到斷言的人都可以在其到期前使用它。 |
斷言承載範例:
{
"iss": "https://idp.example.com",
"sub": "workload:prod:claude-integration-backend",
"aud": "YOUR_CONFIGURED_AUDIENCE",
"iat": 1791230000,
"exp": 1791230300
}請在您的後端允許的範圍內,將主體模式和宣告條件設定得越窄越好。auth.claude.com 會接受來自您身分識別提供者且符合這些條件的任何 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 端點會傳回 HTTP 201,包含 request_uri 和 expires_in(600 秒)。
範圍
| 類別 | 範圍 | 說明 | 連線類型 | 用戶端類型 |
|---|---|---|---|---|
| 一般 | 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 時不存在。 |
若要重新整理,請傳送設為 refresh_token 的 grant_type、您的 refresh_token,以及用戶端驗證中的參數。計費連線的重新整理會遵循計費連線的 OAuth 權杖中的規則。
計費連線的 OAuth 權杖
對於計費連線,權杖端點會傳回該連線的存取權杖。此權杖會在應用程式的 connection_token_workspace_id 設定所指定的工作區中,以您應用程式的營運者服務帳戶身分進行驗證。在 /v1/messages 和 /v1/chat/completions 上,使用此權杖的請求只會計費至該連線的客戶,不會計費至其他任何對象。當客戶也核准了 offline_access 時,權杖端點也會傳回重新整理權杖,而 refresh_token 授權會同時更新這兩個權杖。如需設定與逐步說明,請參閱 Linked billing 頁面上的每個連線的 OAuth token。
這兩種授權都使用權杖請求與回應中的參數,並搭配用戶端驗證。重新整理時不得傳送 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 秒後,它會撤銷該連線的所有權杖並終止連線。重新整理 token說明了重新整理的規則和錯誤。
以下每個事件都會撤銷該連線的權杖,包括目前的存取權杖:
- 客戶或您解除連結。
- 客戶針對同一使用者設定檔核准了範圍不同的新授權請求,且您交換了該核准的授權碼。新連線會取代先前的連線。
- 權杖運作所在的工作區遭到封存。
如需了解 Claude API 如何對使用連線存取權杖的請求計費,請參閱使用連線的存取 token 呼叫 Claude。
撤銷
請以 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。 - 以星號作為連接埠註冊的本機開發 URI(例如
http://localhost:*/callback)可符合任何連接埠。 - 每個應用程式最多可註冊 10 個重新導向 URI。
- 僅當
redirect_uri與已註冊的 URI 相符時,auth.claude.com才會將錯誤傳送至您的重新導向 URI。對於任何其他redirect_uri,auth.claude.com不會重新導向瀏覽器。
錯誤
重新導向時的錯誤
auth.claude.com 會以 error、error_description 和 state 查詢參數的形式,在您的重新導向 URI 上傳回錯誤。它們是標準的 OAuth 2.0 錯誤(RFC 6749),但 user_profile_already_linked 除外,它是 Anthropic 特有的錯誤。
| 錯誤 | 發生時機 | 應向使用者顯示的內容 |
|---|---|---|
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,並確認您的身分識別提供者是以您 JWKS 中的金鑰簽署它。 |
invalid_scope | 此應用程式或此連線類型不允許所請求的範圍。對於計費連線的權杖,這也表示重新整理時傳送了它不接受的 scope 參數,或 billing:attribution 已不再為您的應用程式註冊。在授權碼交換時,第二種原因會耗用掉該授權碼。 |
invalid_grant | 授權碼已過期、您已使用過它,或它與 redirect_uri 或 code_verifier 不相符。對於重新整理,表示重新整理權杖已過期或不再有效:請依照重新整理 token進行。 |
unauthorized_client | 您的應用程式未設定為可處理此請求。對於 Linked billing,請先檢查應用程式的營運者服務帳戶及其工作區:請參閱授權碼交換傳回 unauthorized_client。對於計費連線的權杖,error_description 會說明原因,例如缺少工作區。此拒絕不會耗用授權碼,也不會撤銷任何重新整理權杖。 |
user_profile_already_linked | 僅限 Linked billing,來自權杖端點。在核准與此請求之間,該使用者設定檔已透過其他客戶組織連結至您的應用程式,或客戶的組織已透過其他使用者設定檔連結。 |
如果 auth.claude.com 對請求進行速率限制、發生服務中斷,或收到不明的 grant_type 或超過長度限制的參數,它會以不同的格式傳回錯誤,該格式可能不是 JSON。僅在 HTTP 429 和 5xx 回應時搭配退避機制重試。請將任何其他狀態視為請求中的錯誤。對於計費連線的重新整理,請依照重新整理 token進行,而非使用一般的退避機制。如果回應包含 retry-after 標頭,請至少等待該時間。請從您自己的程式碼傳送下一個請求,不要依賴 HTTP 用戶端程式庫的自動重試:它們可能不會針對此類回應執行。重新整理 token也說明了何時重試是安全的,因為已使用過的重新整理權杖在您再次傳送時可能會終止連線。
來自撤銷端點的錯誤
對於 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 不會為被拒絕的請求向任一組織計費。所有 402 和 403 回應都不可重試,但新連線建立後 10 秒內的 user_profile_not_billable 拒絕除外。
| 狀態 | 錯誤類型與代碼 | 發生時機 |
|---|---|---|
| 400 | invalid_request_error | 請求傳送了 billing_policy 卻未附帶 user-profiles-billing-2026-10-01 beta 標頭。或者 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)。 |
| 身分識別提供者 | 您自有基礎架構中的服務,負責為您的後端簽署短期 JWT,並以 JSON Web Key Set(JWKS)發布其公開金鑰,例如您雲端供應商的工作負載身分識別服務,或您自己符合 OIDC 規範的簽發者。在這些頁面中,「您的身分識別提供者」一律指此服務,而非 Anthropic。 |
| 用戶端斷言 | 由您的身分識別提供者簽署、並由您的後端傳送以驗證您 OAuth 應用程式的短期 JWT。這就是 private_key_jwt 用戶端驗證方法(RFC 7523)。 |
| 推送授權請求(PAR) | 一種請求,您的後端會將授權參數直接傳送至 auth.claude.com,並收到用於瀏覽器重新導向的 request_uri(RFC 9126)。 |
| 工作負載身分聯合 | Claude Console 的功能,您的組織透過它註冊您的身分識別提供者,讓 Anthropic 接受以您 JWKS 中的金鑰簽署的 JWT。 |
| 探索文件 | 列出 Anthropic 簽發者、端點和簽署金鑰的 OIDC 文件。 |
| 使用者設定檔 | 您在自己的 Claude 組織中建立、用以代表您某位客戶的記錄。計費連線會將使用者設定檔連結至該客戶的 Claude 組織。 |
| 服務帳戶 | 您 Claude 組織中的非人類帳戶。對於 Linked billing,您的 OAuth 應用程式會連結至一個服務帳戶,即其營運者服務帳戶,且您的後端在傳送向客戶計費的請求時,會以該服務帳戶的身分進行驗證。 |
| 連線的 OAuth 權杖 | auth.claude.com 為計費連線傳回的存取權杖,以及當客戶也核准了 offline_access 時所傳回的重新整理權杖。此存取權杖會以營運者服務帳戶的身分進行驗證,且只能向該連線的使用者設定檔計費。請參閱計費連線的 OAuth 權杖。 |
這個頁面有幫助嗎?