Claude Platform Docs
AdministraçãoClaude Platform OAuth

Referência de OAuth

Endpoints, autenticação de cliente, parâmetros de solicitação, escopos, respostas de token, revogação, tempos de vida, regras de URI de redirecionamento e erros.

Esta página reúne os endpoints, parâmetros, regras de validação e mapeamentos de erros para o Claude Platform OAuth. Para um guia passo a passo, consulte Linked billing.

Endpoints

EndpointURL
Emissorhttps://identity.anthropic.com/users
Documento de descobertahttps://identity.anthropic.com/users/.well-known/openid-configuration
Chaves de assinatura (JWKS)O jwks_uri no documento de descoberta, hospedado em identity.anthropic.com
Endpoint de autorização (página de login e consentimento)https://auth.claude.com/oauth/authorize
Endpoint de pushed authorization request (PAR)https://auth.claude.com/v1/oauth/par
Endpoint de tokenhttps://auth.claude.com/v1/oauth/token
Endpoint de revogaçãohttps://auth.claude.com/v1/oauth/revoke
Claude API (perfis de usuário e solicitações que cobram um cliente)https://api.anthropic.com

Leia as chaves de assinatura a partir do “discovery document” (documento de descoberta) em vez de codificá-las diretamente. O documento de descoberta não lista o endpoint PAR nem o endpoint de revogação, então use as URLs desta tabela.

Valores do documento de descoberta

CampoValor
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

auth.claude.com retorna um token de atualização para Linked billing somente quando o cliente aprovou offline_access junto com billing:attribution: consulte Tokens OAuth para uma conexão de faturamento.

Autenticação de cliente

auth.claude.com autentica um “confidential client” (cliente confidencial) com o método private_key_jwt (RFC 7523). Envie estes parâmetros em todas as solicitações ao endpoint PAR, ao endpoint de token e ao endpoint de revogação. Nunca envie credenciais em uma query string de URL: auth.claude.com as rejeita.

ParâmetroValor
client_idO client ID do seu app OAuth
client_assertion_typeurn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertionUm JWT do seu provedor de identidade com as claims em Claims da client assertion

Claims da client assertion

Uma “client assertion” (asserção de cliente) deve conter todas as claims a seguir, e seu cabeçalho deve conter o kid de uma chave no seu JWKS.

ClaimRequisito
issA URL do emissor do seu provedor de identidade, exatamente como registrada por meio da Workload Identity Federation
subUm valor que corresponda ao padrão de subject nas configurações de autenticação de cliente do seu app, se você definiu um
audExatamente um público (audience): o valor nas configurações de autenticação de cliente do seu app. auth.claude.com rejeita uma asserção que liste mais de um público.
iatO momento em que seu provedor de identidade emitiu o JWT
expO momento de expiração, no máximo 1 hora após iat. Use um tempo de vida menor sempre que possível: qualquer pessoa que intercepte uma asserção pode usá-la até que ela expire.

Exemplo de payload da asserção:

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

Torne o padrão de subject e as condições de claims tão restritos quanto seu back-end permitir. auth.claude.com aceita qualquer JWT do seu provedor de identidade que corresponda a eles como autenticação do seu app.

Parâmetros da solicitação de autorização

Envie estes parâmetros, exceto request_uri, no corpo JSON de uma “pushed authorization request” (solicitação de autorização enviada previamente).

ParâmetroLinked billingDescrição
response_typeObrigatórioO valor code
client_idObrigatórioO client ID do seu app OAuth
redirect_uriObrigatórioUm URI que corresponda exatamente a um URI de redirecionamento registrado, com até 2048 caracteres
scopeObrigatórioPara uma conexão de faturamento, billing:attribution ou billing:attribution offline_access. Consulte Escopos.
stateObrigatórioUm valor aleatório de uso único, com até 2048 caracteres, que você verifica no callback
code_challengeObrigatórioBASE64URL(SHA256(code_verifier)), em que o code_verifier tem de 43 a 128 caracteres
code_challenge_methodObrigatórioO valor S256
connection_typeObrigatórioO valor organization_shared. Esse valor solicita uma conexão de organização para faturamento.
connection_auth_targetObrigatórioPara qual organização as solicitações da conexão são encaminhadas. Para Linked billing, envie platform (a proprietária do app OAuth).
user_profile_idObrigatórioO ID de um perfil de usuário ativo na sua organização que representa o cliente
request_uriObrigatórioO valor que o endpoint PAR retornou. Envie-o ao endpoint de autorização com client_id e nenhum outro parâmetro.

O endpoint PAR retorna HTTP 201 com request_uri e expires_in (600 segundos).

Escopos

CategoriaEscopoDescriçãoTipo de conexãoTipo de cliente
Geraloffline_accessDá ao app um token de atualização que representa os outros escopos solicitados. Em uma conexão organization_shared, envie-o somente junto com billing:attribution.organization_sharedConfidencial
Faturamentobilling:attributionUma conexão que permite cobrar da organização Claude de um cliente as solicitações à Claude API que esse cliente orienta você a fazer. Envie-o sozinho, ou junto com offline_access para também obter um token de atualização. Consulte Tokens OAuth para uma conexão de faturamento.organization_sharedConfidencial
Faturamentoorg:billing_attributionDescontinuado: use billing:attribution.organization_sharedConfidencial

Solicitação e resposta de token

Envie solicitações de token para https://auth.claude.com/v1/oauth/token com um corpo JSON.

ParâmetroValor
grant_typeauthorization_code
codeO código do callback
redirect_uriO mesmo redirect_uri que você enviou na solicitação de autorização
code_verifierO code verifier do PKCE
client_id, client_assertion_type, client_assertionComo em Autenticação de cliente

A resposta de token contém estes campos:

Campo da respostaLinked billing
access_tokenO token de acesso da conexão
token_typeBearer
expires_inNo máximo 3600
scopeworkspace:inference
connection_idO ID da conexão, por exemplo ocon_EXAMPLE. Armazene-o.
refresh_tokenRetornado somente quando o cliente aprovou offline_access
refresh_token_expires_inSegundos até refresh_token expirar. Ausente quando não há refresh_token.

Para renovar, envie grant_type definido como refresh_token, seu refresh_token e os parâmetros em Autenticação de cliente. A renovação de uma conexão de faturamento segue as regras em Tokens OAuth para uma conexão de faturamento.

Tokens OAuth para uma conexão de faturamento

Para uma conexão de faturamento, o endpoint de token retorna o token de acesso da conexão. O token se autentica como a “operator service account” (conta de serviço operadora) do seu app, no workspace indicado pela configuração connection_token_workspace_id do app. Em /v1/messages e /v1/chat/completions, uma solicitação com ele é cobrada do cliente dessa conexão e de nenhum outro. Quando o cliente também aprovou offline_access, o endpoint de token retorna também um token de atualização, e a concessão refresh_token renova ambos os tokens. Para a configuração e o passo a passo, consulte Tokens OAuth para cada conexão na página de Linked billing.

Ambas as concessões usam os parâmetros em Solicitação e resposta de token, com Autenticação de cliente. Uma renovação não deve enviar um parâmetro scope. A resposta de token contém estes campos:

Campo da respostaValor
access_tokenO token de acesso da conexão
token_typeBearer
expires_inSegundos até o token de acesso expirar, no máximo 3600
scopeSempre workspace:inference
connection_idO ID da conexão, por exemplo ocon_EXAMPLE. Somente a concessão authorization_code o retorna.
refresh_tokenO token de atualização da conexão. Retornado somente quando o cliente aprovou offline_access.
refresh_token_expires_inSegundos até refresh_token expirar

Cada renovação retorna um novo access_token e um novo refresh_token. O token de atualização que você enviou é substituído, e o token de acesso anterior para de funcionar em poucos minutos. Você pode enviar o token de atualização substituído mais uma vez, em até 30 segundos após a renovação que o substituiu, para repetir uma solicitação cuja resposta você perdeu. Essa segunda solicitação retorna outro novo par e revoga o par da resposta perdida: use somente o par mais recente. Uma terceira solicitação com o token substituído recebe invalid_grant, assim como uma segunda solicitação que chegue após os 30 segundos. Dentro dos 30 segundos, essa solicitação não revoga nada. Após os 30 segundos, ela revoga todos os tokens da conexão e encerra a conexão. Atualizar os tokens contém as regras e os erros de uma renovação.

Cada um destes eventos revoga os tokens da conexão, incluindo o token de acesso atual:

  • O cliente ou você desvincula.
  • O cliente aprova uma nova solicitação de autorização com escopos diferentes para o mesmo perfil de usuário, e você troca o código dessa aprovação. A nova conexão substitui a anterior.
  • O workspace em que os tokens são executados é arquivado.

Para saber como a Claude API cobra uma solicitação com o token de acesso de uma conexão, consulte Chamar o Claude com o token de acesso de uma conexão.

Revogação

Envie solicitações de revogação para https://auth.claude.com/v1/oauth/revoke com um corpo JSON ou codificado como formulário. O endpoint segue a RFC 7009 e também aceita IDs de conexão e de perfil de usuário.

Envie os parâmetros em Autenticação de cliente e exatamente um dos parâmetros desta tabela. O aud da client assertion é o valor nas configurações de autenticação de cliente do seu app, não a URL de revogação.

ParâmetroO que encerra
connection_idUma das conexões do seu app, informada como um ID ocon_
user_profile_idTodas as conexões do seu app em um perfil de usuário, informado como um ID uprof_
tokenPara Linked billing, envie connection_id ou user_profile_id em vez disso: enviar um token de acesso pode não encerrar a conexão.

auth.claude.com aceita token_type_hint e o ignora.

O endpoint retorna HTTP 200 e os IDs das conexões que a solicitação encerrou:

{
  "revoked_connection_ids": ["ocon_EXAMPLE"]
}

A lista fica vazia se o token ou o ID for desconhecido ou pertencer a outro app, se a conexão já tiver sido encerrada ou se a solicitação tiver encerrado um token, mas nenhuma conexão. A resposta não informa qual.

Depois que uma conexão de faturamento é encerrada, a Claude API recusa solicitações que cobram esse cliente, com user_profile_not_billable, e os tokens OAuth da conexão param de funcionar. Depois disso, não dependa de um token de acesso de uma conexão aprovada com o escopo descontinuado org:billing_attribution: ele pode parar de funcionar imediatamente ou funcionar até expirar.

Tempos de vida

ItemTempo de vida
request_uri do endpoint PAR10 minutos, uso único
Código de autorização5 minutos, uso único
access_tokenAté 1 hora
refresh_tokenAté 1 ano a partir da troca do código. Uma renovação não o estende.

Esses são os valores atuais. Leia expires_in e refresh_token_expires_in de cada resposta em vez de depender de valores fixos.

Regras de URI de redirecionamento

  • Cada redirect_uri deve corresponder exatamente a um URI registrado no seu app. auth.claude.com não usa correspondência por curinga ou por prefixo.
  • Todo URI de redirecionamento deve usar HTTPS e não deve conter um fragmento. URIs de desenvolvimento local em localhost, 127.0.0.1 ou [::1] podem usar HTTP.
  • Um URI de desenvolvimento local registrado com um asterisco como porta, como http://localhost:*/callback, corresponde a qualquer porta.
  • Você pode registrar até 10 URIs de redirecionamento para cada app.
  • auth.claude.com envia erros para seu URI de redirecionamento somente quando o redirect_uri corresponde a um URI registrado. Para qualquer outro redirect_uri, auth.claude.com não redireciona o navegador.

Erros

Erros no redirecionamento

auth.claude.com retorna erros como parâmetros de consulta error, error_description e state no seu URI de redirecionamento. Eles são erros padrão do OAuth 2.0 (RFC 6749), exceto user_profile_already_linked, que é específico da Anthropic.

ErroQuandoO que mostrar ao seu usuário
access_deniedA pessoa recusou, ou não pode aprovar esta solicitação. Para uma conexão de faturamento, a pessoa deve ser administradora de uma organização Claude.Explique que a conexão não foi concluída e não presuma que a pessoa recusou. Para uma conexão de faturamento, siga Seu URI de redirecionamento recebe error=access_denied no guia de Linked billing, que lista as causas e o que dizer à pessoa. Caso contrário, peça que a pessoa entre em contato com você.
server_errorauth.claude.com não conseguiu processar a solicitação.Peça ao usuário que tente novamente.
user_profile_already_linkedSomente Linked billing. A organização do cliente já está vinculada ao seu app por meio de um perfil de usuário diferente. Cada organização cliente pode ter uma conexão com seu app. auth.claude.com já pediu ao administrador que entre em contato com você.Explique que a organização dele já está vinculada ao seu app.

Se o request_uri expirou ou você já o usou, auth.claude.com mostra uma página de erro e não redireciona o navegador de volta ao seu app. Inicie o fluxo novamente com uma nova pushed authorization request.

Erros dos endpoints PAR e de token

Esses endpoints retornam um corpo JSON com error e error_description.

ErroQuando
invalid_requestUm parâmetro obrigatório está ausente ou é inválido, por exemplo um state ou desafio PKCE ausente, ou um user_profile_id que não é o ID de um perfil de usuário ativo na sua organização.
invalid_clientauth.claude.com não conseguiu autenticar seu app: o client ID é desconhecido ou a client assertion falhou na verificação. Confira iss, sub e aud da asserção com as configurações de autenticação de cliente do seu app e verifique se seu provedor de identidade a assinou com uma chave do seu JWKS.
invalid_scopeO escopo solicitado não é permitido para este app ou este tipo de conexão. Para os tokens de uma conexão de faturamento, isso também significa que uma renovação enviou um parâmetro scope, que ela não aceita, ou que billing:attribution não está mais registrado para seu app. Na troca do código, essa segunda causa consome o código.
invalid_grantO código expirou, você já o usou ou ele não corresponde ao redirect_uri ou ao code_verifier. Para uma renovação, o token de atualização expirou ou não é mais válido: siga Atualizar os tokens.
unauthorized_clientSeu app não está configurado para esta solicitação. Para Linked billing, verifique primeiro a conta de serviço operadora do app e o workspace dela: consulte A troca do código retorna unauthorized_client. Para os tokens de uma conexão de faturamento, error_description informa a causa, por exemplo um workspace ausente. Essa recusa não consome nenhum código e não revoga nenhum token de atualização.
user_profile_already_linkedSomente Linked billing, a partir do endpoint de token. Entre a aprovação e esta solicitação, o perfil de usuário foi vinculado ao seu app por meio de uma organização cliente diferente, ou a organização do cliente foi vinculada por meio de um perfil de usuário diferente.

Se auth.claude.com aplicar um “rate limit” (limite de taxa) a uma solicitação, tiver uma interrupção ou receber um grant_type desconhecido ou um parâmetro maior que seu limite, ele retorna um erro em um formato diferente, que pode não ser JSON. Tente novamente apenas em respostas HTTP 429 e 5xx, com backoff. Trate qualquer outro status como uma falha na solicitação. Para a renovação de uma conexão de faturamento, siga Atualizar os tokens em vez de um backoff genérico. Se a resposta tiver um cabeçalho retry-after, aguarde pelo menos esse tempo. Envie a próxima solicitação a partir do seu próprio código e não dependa das novas tentativas automáticas de uma biblioteca cliente HTTP: elas podem não ser executadas para esse tipo de resposta. Atualizar os tokens também informa quando uma nova tentativa é segura, porque um token de atualização que já foi usado pode encerrar a conexão quando você o envia novamente.

Erros do endpoint de revogação

Para a maioria das solicitações que auth.claude.com recusa, o endpoint de revogação retorna HTTP 400 e um corpo JSON com error e error_description.

ErroQuando
invalid_requestUm parâmetro obrigatório está ausente ou é inválido, por exemplo um client_id ausente. A solicitação não envia nenhum de token, connection_id e user_profile_id, ou envia mais de um deles. Um ID está malformado, por exemplo tem o prefixo errado. Uma credencial ou token está na query string da URL. O perfil de usuário tem conexões demais para uma única solicitação: a solicitação pode ter encerrado algumas delas, então encerre o restante com connection_id.
invalid_clientauth.claude.com não conseguiu autenticar seu app. Para saber o que verificar, consulte invalid_client em Erros dos endpoints PAR e de token.
unauthorized_clientSeu app não está configurado para esta solicitação. Entre em contato com sua equipe de conta da Anthropic.

As respostas da próxima tabela usam um formato diferente, que pode não ser JSON. Quando o corpo é JSON, error é um objeto, não uma string.

StatusQuandoO que fazer
400Um parâmetro é maior que seu limite.Corrija a solicitação. Não tente novamente.
429Muitas solicitações com falha vieram do seu endereço IP.Tente novamente com backoff.
500auth.claude.com não conseguiu processar a solicitação.Tente novamente com backoff. Se isso continuar acontecendo, entre em contato com sua equipe de conta da Anthropic.
501A Anthropic não habilitou este endpoint para sua organização.Não tente novamente. Entre em contato com sua equipe de conta da Anthropic.
503A solicitação não foi concluída. O que ela encerrou permanece encerrado.Tente novamente com backoff, com os mesmos parâmetros e uma nova client assertion. A nova tentativa conclui o restante, e a lista dela omite as conexões que a solicitação anterior encerrou. Se você enviou user_profile_id, tente novamente em até um dia: depois disso, uma nova tentativa pode retornar 200 com uma lista vazia e não concluir nada. Uma nova tentativa com cada connection_id funciona a qualquer momento.

Erros de faturamento

Estes se aplicam a solicitações à Claude API que definem billing_policy.bill_to como "user_profile" ou que se autenticam com o token de acesso de uma conexão de faturamento. A Claude API não cobra nenhuma das organizações por uma solicitação recusada. Nenhuma das respostas 402 e 403 pode ser repetida, exceto uma recusa user_profile_not_billable nos primeiros 10 segundos após uma nova conexão.

StatusTipo e código de erroQuando
400invalid_request_errorA solicitação envia billing_policy sem o cabeçalho beta user-profiles-billing-2026-10-01. Ou o objeto billing_policy tem um campo ausente ou inválido. Com o token de acesso de uma conexão de faturamento, bill_to pode ser omitido. Ou a solicitação usa execução de código fora da combinação permitida.
400invalid_request_error, user_profile_requiredbill_to é "user_profile", a solicitação não inclui um ID de perfil de usuário e não se autentica com o token de acesso de uma conexão de faturamento.
400invalid_request_error, sem código de erroA solicitação se autentica com o token de acesso de uma conexão de faturamento e define bill_to como "self" ou indica um perfil de usuário diferente daquele ao qual o token está limitado. Cada uma dessas duas recusas informa o problema em error.message.
401authentication_errorA solicitação se autentica com o token de acesso de uma conexão de faturamento que expirou, que foi substituído por uma renovação ou cuja conexão foi encerrada. A mensagem informa se o token expirou ou foi revogado. Envie a solicitação novamente com o token de acesso atual ou vincule o cliente novamente se a conexão tiver sido encerrada. Depois que uma conexão é encerrada, cada nova solicitação com o token de acesso dela pode receber este 401 ou um 403 user_profile_not_billable, sem ordem fixa.
402billing_error, linked_organization_spend_limit_reachedA organização cliente atingiu um limite de gastos que ela definiu, para o seu app OAuth ou para a organização inteira. A Claude API envia o mesmo código quando a organização não tem crédito que possa pagar pela solicitação. A resposta não informa qual. Peça ao cliente que verifique ambos os limites e o saldo de crédito dela. A seção Erros esperados para Linked billing informa onde cada um é definido e o que alterar.
402billing_error, linked_organization_billing_unavailableA Anthropic não consegue cobrar a organização cliente no momento devido a um problema com a própria conta Anthropic dessa organização. O mesmo código encerra uma resposta que o Claude já começou quando o crédito da organização acaba. Peça ao cliente que verifique seu status de faturamento com a Anthropic.
403permission_error, sem código de erroA Anthropic não cobra sua organização diretamente, portanto não pode cobrar clientes em seu nome.
403permission_error, user_profile_not_billableO perfil de usuário não tem conexão com uma organização cliente, um administrador ou seu back-end encerrou a conexão, a organização cliente não paga à Anthropic diretamente pelo uso da API (tanto créditos pré-pagos quanto cobrança por fatura contam), ou a solicitação não se autentica como a conta de serviço do seu app. A resposta não informa qual. O token de acesso de uma conexão também pode recebê-lo depois que a conexão é encerrada. A seção Causas de user_profile_not_billable informa o que verificar em cada caso.
503overloaded_errorA Claude API temporariamente não consegue confirmar se pode cobrar o cliente. Tente a solicitação novamente. Se a resposta incluir um cabeçalho retry-after, aguarde esse tempo antes de tentar novamente.

Em /v1/messages, o código de erro está em error.details.error_code. Em /v1/chat/completions, error.type é sempre invalid_request_error, error.code contém o tipo de erro da Anthropic (por exemplo permission_error ou billing_error) e a resposta não tem código de erro, então faça a correspondência pelo status HTTP e por error.code.

Padrões

PadrãoOnde se aplica
OAuth 2.0 (RFC 6749)Fluxo de código de autorização, endpoint de token e respostas de erro
PKCE (RFC 7636)Obrigatório com S256 em todas as solicitações de autorização
Pushed authorization requests (RFC 9126)Obrigatório para Linked billing.
Revogação de token (RFC 7009)O endpoint de revogação, que também aceita IDs de conexão e de perfil de usuário e retorna os IDs das conexões que encerrou
Autenticação de cliente JWT (RFC 7523)A autenticação de cliente private_key_jwt nos endpoints PAR, de token e de revogação, e a troca de token da conta de serviço para solicitações que cobram um cliente

Termos usados nestas páginas

Os significados a seguir se aplicam somente ao Claude Platform OAuth.

TermoSignificado
Organização ClaudeUma conta de organização na Anthropic. Sua empresa tem uma, assim como cada cliente que vincula sua organização para faturamento.
AdministradorUm membro de uma organização Claude com a função Admin ou Faturamento.
App OAuthO registro na sua organização Claude que identifica seu produto para auth.claude.com. Ele tem um client ID, um nome, um logotipo, uma URL de página inicial, URIs de redirecionamento e os tipos de conexão que suporta.
Tipo de conexãoQuem aprova uma conexão: um administrador em nome de uma organização inteira (organization_shared, para Linked billing).
Provedor de identidadeO serviço na sua própria infraestrutura que assina JWTs de curta duração para seu back-end e publica suas chaves públicas como um JSON Web Key Set (JWKS), como o serviço de identidade de workload do seu provedor de nuvem ou seu próprio emissor compatível com OIDC. Nestas páginas, “seu provedor de identidade” sempre se refere a esse serviço, não à Anthropic.
Client assertionUm JWT de curta duração que seu provedor de identidade assina e seu back-end envia para autenticar seu app OAuth. Este é o método de autenticação de cliente private_key_jwt (RFC 7523).
Pushed authorization request (PAR)Uma solicitação na qual seu back-end envia os parâmetros de autorização diretamente para auth.claude.com e recebe um request_uri para usar no redirecionamento do navegador (RFC 9126).
Workload Identity FederationO recurso do Claude Console por meio do qual sua organização registra seu provedor de identidade, para que a Anthropic aceite JWTs assinados com as chaves do seu JWKS.
Documento de descobertaO documento OIDC que lista o emissor, os endpoints e as chaves de assinatura da Anthropic.
Perfil de usuárioUm registro que você cria na sua própria organização Claude para representar um dos seus clientes. Uma conexão de faturamento vincula um perfil de usuário à organização Claude do cliente.
Conta de serviçoUma conta não humana na sua organização Claude. Para Linked billing, seu app OAuth é vinculado a uma conta de serviço, sua conta de serviço operadora, e seu back-end se autentica como essa conta de serviço ao enviar uma solicitação que cobra um cliente.
Tokens OAuth da conexãoO token de acesso que auth.claude.com retorna para uma conexão de faturamento e o token de atualização que ele retorna quando o cliente também aprovou offline_access. O token de acesso se autentica como a conta de serviço operadora e pode cobrar somente o perfil de usuário dessa conexão. Consulte Tokens OAuth para uma conexão de faturamento.

Esta página foi útil?