Claude Platform Docs
管理Claude Platform OAuth

OAuth 参考

端点、客户端身份验证、请求参数、范围、令牌响应、撤销、有效期、重定向 URI 规则和错误。

此页面汇总了 Claude Platform OAuth 的端点、参数、验证规则和错误映射。有关操作演练,请参阅 Linked billing。

端点

端点URL
颁发者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
“Pushed authorization request”(推送授权请求),即 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。

发现文档值

字段值
issuerhttps://identity.anthropic.com/users
authorization_endpointhttps://auth.claude.com/oauth/authorize
token_endpointhttps://auth.claude.com/v1/oauth/token
jwks_urihttps://identity.anthropic.com/users/jwks.json
response_types_supportedcode
grant_types_supportedauthorization_code, refresh_token
code_challenge_methods_supportedS256
token_endpoint_auth_methods_supportedprivate_key_jwt
id_token_signing_alg_values_supportedES256
scopes_supportedopenid, email
subject_types_supportedpublic, pairwise

对于 Linked billing,仅当客户同时批准了 offline_access 和 billing:attribution 时,auth.claude.com 才会返回刷新令牌:请参阅计费连接的 OAuth 令牌。

客户端身份验证

auth.claude.com 使用 private_key_jwt 方法(RFC 7523)对机密客户端进行身份验证。请在每个发往 PAR 端点、令牌端点和撤销端点的请求中发送这些参数。切勿在 URL 查询字符串中发送凭据:auth.claude.com 会拒绝它们。

参数值
client_id您的 OAuth 应用的客户端 ID
client_assertion_typeurn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion来自您的身份提供商的 JWT,包含客户端断言声明中的声明

客户端断言声明

客户端断言必须包含以下所有声明,并且其标头必须包含您 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,作为您应用的身份验证。

授权请求参数

请在推送授权请求的 JSON 正文中发送这些参数(request_uri 除外)。

参数Linked billing描述
response_type必需值 code
client_id必需您的 OAuth 应用的客户端 ID
redirect_uri必需与已注册的重定向 URI 完全匹配的 URI,最多 2048 个字符
scope必需对于计费连接,为 billing:attribution 或 billing:attribution offline_access。请参阅范围。
state必需一个随机的一次性值,最多 2048 个字符,您需要在回调时检查它
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_typeauthorization_code
code回调中的授权码
redirect_uri与您在授权请求中发送的相同的 redirect_uri
code_verifierPKCE 代码验证器
client_id, client_assertion_type, client_assertion如客户端身份验证中所述

令牌响应包含以下字段:

响应字段Linked billing
access_token连接的访问令牌
token_typeBearer
expires_in最多 3600
scopeworkspace:inference
connection_id连接 ID,例如 ocon_EXAMPLE。请存储它。
refresh_token仅当客户批准了 offline_access 时返回
refresh_token_expires_inrefresh_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 令牌。

两种授权都使用令牌请求和响应中的参数,以及客户端身份验证。刷新请求不得发送 scope 参数。令牌响应包含以下字段:

响应字段值
access_token连接的访问令牌
token_typeBearer
expires_in访问令牌过期前的秒数,最多 3600
scope始终为 workspace:inference
connection_id连接 ID,例如 ocon_EXAMPLE。仅 authorization_code 授权会返回它。
refresh_token连接的刷新令牌。仅当客户批准了 offline_access 时返回。
refresh_token_expires_inrefresh_token 过期前的秒数

每次刷新都会返回新的 access_token 和新的 refresh_token。您发送的刷新令牌会被替换,先前的访问令牌会在几分钟内失效。您可以在替换它的那次刷新之后 30 秒内,再发送一次已被替换的刷新令牌,以重复一个丢失了响应的请求。该第二次请求会返回另一对新令牌,并撤销丢失的响应中的那对令牌:请仅使用最新的一对。使用已被替换令牌的第三次请求会收到 invalid_grant,在 30 秒之后到达的第二次请求也是如此。在这 30 秒内,此类请求不会撤销任何内容。超过 30 秒后,它会撤销该连接的所有令牌并终止该连接。刷新令牌介绍了刷新的规则和错误。

以下每个事件都会撤销该连接的令牌,包括当前的访问令牌:

  • 客户或您解除关联。
  • 客户针对同一用户配置文件批准了一个范围不同的新授权请求,且您兑换了该批准的授权码。新连接将取代先前的连接。
  • 令牌所运行的工作区被归档。

有关 Claude API 如何对使用连接访问令牌的请求进行计费,请参阅使用连接的访问令牌调用 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_uri10 分钟,一次性使用
授权码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_errorauth.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_clientauth.claude.com 无法对您的应用进行身份验证:客户端 ID 未知,或客户端断言验证失败。请根据您应用的客户端身份验证设置检查断言的 iss、sub 和 aud,并确认您的身份提供商使用了您 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 对请求进行了速率限制、发生故障,或收到未知的 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_clientauth.claude.com 无法对您的应用进行身份验证。有关需要检查的内容,请参阅来自 PAR 端点和令牌端点的错误中的 invalid_client。
unauthorized_client您的应用未设置为处理此请求。请联系您的 Anthropic 客户团队。

下表中的响应使用不同的格式,该格式可能不是 JSON。当正文为 JSON 时,error 是一个对象,而不是字符串。

状态何时出现处理方式
400某个参数超出其长度限制。修正请求。不要重试。
429来自您 IP 地址的失败请求过多。采用退避策略重试。
500auth.claude.com 处理请求失败。采用退避策略重试。如果问题持续出现,请联系您的 Anthropic 客户团队。
501Anthropic 尚未为您的组织启用此端点。不要重试。请联系您的 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 拒绝除外。

状态错误类型和代码何时出现
400invalid_request_error请求发送了 billing_policy 但未附带 user-profiles-billing-2026-10-01 beta 标头。或者 billing_policy 对象缺少字段或字段无效。使用计费连接的访问令牌时,可以省略 bill_to。或者请求在允许的组合之外使用了代码执行。
400invalid_request_error, user_profile_requiredbill_to 为 "user_profile",请求未包含用户配置文件 ID,且未使用计费连接的访问令牌进行身份验证。
400invalid_request_error,无错误代码请求使用计费连接的访问令牌进行身份验证,并且将 bill_to 设置为 "self",或指定了该令牌所限定的用户配置文件以外的其他用户配置文件。这两种拒绝都会在 error.message 中说明问题所在。
401authentication_error请求使用的计费连接访问令牌已过期、已被刷新替换,或其连接已终止。消息会说明令牌是已过期还是已被撤销。请使用当前的访问令牌重新发送请求;如果连接已终止,请重新关联客户。连接终止后,每个使用其访问令牌的新请求都可能收到此 401 或 403 user_profile_not_billable,顺序不固定。
402billing_error, linked_organization_spend_limit_reached客户组织已达到其设置的支出限制,该限制可能针对您的 OAuth 应用,也可能针对整个组织。当该组织没有可用于支付该请求的额度时,Claude API 也会发送相同的代码。响应不会说明是哪一种。请让客户检查这两项限制及其额度余额。Linked billing 的预期错误部分说明了每项的设置位置以及需要更改的内容。
402billing_error, linked_organization_billing_unavailable由于该客户组织自身的 Anthropic 账户存在问题,Anthropic 目前无法向其计费。当该组织的额度耗尽时,相同的代码也会终止 Claude 已开始的回复。请让客户向 Anthropic 检查其计费状态。
403permission_error,无错误代码Anthropic 不直接向您的组织计费,因此无法代表您向客户计费。
403permission_error, user_profile_not_billable该用户配置文件未与任何客户组织建立连接、管理员或您的后端已终止连接、客户组织未就其 API 用量直接向 Anthropic 付款(预付额度和发票计费均符合条件),或请求未以您应用的服务账户身份进行身份验证。响应不会说明是哪一种。连接终止后,连接的访问令牌也可能收到此错误。user_profile_not_billable 的原因说明了每种情况需要检查的内容。
503overloaded_errorClaude 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 令牌。

此页面对您有帮助吗?