---
title: Referência de OAuth
url: https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference
description: 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.
---

<Warning>
  Claude Platform OAuth é um Beta Service: software de pré-lançamento fornecido nos termos do seu contrato com a Anthropic, como os [Termos de Serviço Comerciais](https://www.anthropic.com/legal/commercial-terms), e os [Termos Específicos do Serviço](https://www.anthropic.com/legal/service-specific-terms). Endpoints, parâmetros e comportamento podem mudar durante o beta. Pode não ser adequado para uso em produção.
</Warning>

Esta página reúne os endpoints, parâmetros, regras de validação e mapeamentos de erros para o [Claude Platform OAuth](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/overview). Para um guia passo a passo, consulte [Linked billing](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections).

## Endpoints

| Endpoint                                                            | URL                                                                            |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Emissor                                                             | `https://identity.anthropic.com/users`                                         |
| Documento de descoberta                                             | `https://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 token                                                   | `https://auth.claude.com/v1/oauth/token`                                       |
| Endpoint de revogação                                               | `https://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

| Campo                                   | Valor                                            |
| --------------------------------------- | ------------------------------------------------ |
| `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` 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection).

## Autenticação de cliente

`auth.claude.com` autentica um “confidential client” (cliente confidencial) com o método `private_key_jwt` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)). 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âmetro               | Valor                                                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`             | O client ID do seu app OAuth                                                                                                                                                                |
| `client_assertion_type` | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`                                                                                                                                    |
| `client_assertion`      | Um JWT do seu provedor de identidade com as claims em [Claims da client assertion](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-assertion-claims) |

### 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.

| Claim | Requisito                                                                                                                                                                                                |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss` | A URL do emissor do seu provedor de identidade, exatamente como registrada por meio da [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation) |
| `sub` | Um valor que corresponda ao padrão de subject nas configurações de autenticação de cliente do seu app, se você definiu um                                                                                |
| `aud` | Exatamente 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.                                  |
| `iat` | O momento em que seu provedor de identidade emitiu o JWT                                                                                                                                                 |
| `exp` | O 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:

```json
{
  "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âmetro                | Linked billing | Descrição                                                                                                                                                                                                   |
| ------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type`          | Obrigatório    | O valor `code`                                                                                                                                                                                              |
| `client_id`              | Obrigatório    | O client ID do seu app OAuth                                                                                                                                                                                |
| `redirect_uri`           | Obrigatório    | Um URI que corresponda exatamente a um URI de redirecionamento registrado, com até 2048 caracteres                                                                                                          |
| `scope`                  | Obrigatório    | Para uma conexão de faturamento, `billing:attribution` ou `billing:attribution offline_access`. Consulte [Escopos](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#scopes). |
| `state`                  | Obrigatório    | Um valor aleatório de uso único, com até 2048 caracteres, que você verifica no callback                                                                                                                     |
| `code_challenge`         | Obrigatório    | `BASE64URL(SHA256(code_verifier))`, em que o `code_verifier` tem de 43 a 128 caracteres                                                                                                                     |
| `code_challenge_method`  | Obrigatório    | O valor `S256`                                                                                                                                                                                              |
| `connection_type`        | Obrigatório    | O valor `organization_shared`. Esse valor solicita uma conexão de organização para faturamento.                                                                                                             |
| `connection_auth_target` | Obrigatório    | Para 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_id`        | Obrigatório    | O ID de um perfil de usuário ativo na sua organização que representa o cliente                                                                                                                              |
| `request_uri`            | Obrigatório    | O 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

| Categoria   | Escopo                    | Descrição                                                                                                                                                                                                                                                                                                                                                                                                        | Tipo de conexão       | Tipo de cliente |
| ----------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------- |
| Geral       | `offline_access`          | Dá 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_shared` | Confidencial    |
| Faturamento | `billing:attribution`     | Uma 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). | `organization_shared` | Confidencial    |
| Faturamento | `org:billing_attribution` | Descontinuado: use `billing:attribution`.                                                                                                                                                                                                                                                                                                                                                                        | `organization_shared` | Confidencial    |

## Solicitação e resposta de token

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

| Parâmetro                                                | Valor                                                                                                                                    |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`                                             | `authorization_code`                                                                                                                     |
| `code`                                                   | O código do callback                                                                                                                     |
| `redirect_uri`                                           | O mesmo `redirect_uri` que você enviou na solicitação de autorização                                                                     |
| `code_verifier`                                          | O code verifier do PKCE                                                                                                                  |
| `client_id`, `client_assertion_type`, `client_assertion` | Como em [Autenticação de cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-authentication) |

A resposta de token contém estes campos:

| Campo da resposta          | Linked billing                                                                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`             | [O token de acesso da conexão](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection) |
| `token_type`               | `Bearer`                                                                                                                                              |
| `expires_in`               | No máximo `3600`                                                                                                                                      |
| `scope`                    | `workspace:inference`                                                                                                                                 |
| `connection_id`            | O ID da conexão, por exemplo `ocon_EXAMPLE`. Armazene-o.                                                                                              |
| `refresh_token`            | Retornado somente quando o cliente aprovou `offline_access`                                                                                           |
| `refresh_token_expires_in` | Segundos 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-authentication). A renovação de uma conexão de faturamento segue as regras em [Tokens OAuth para uma conexão de faturamento](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection).

## 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#terms)) 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) na página de Linked billing.

Ambas as concessões usam os parâmetros em [Solicitação e resposta de token](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#token-request-and-response), com [Autenticação de cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-authentication). Uma renovação não deve enviar um parâmetro `scope`. A resposta de token contém estes campos:

| Campo da resposta          | Valor                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `access_token`             | O token de acesso da conexão                                                                     |
| `token_type`               | `Bearer`                                                                                         |
| `expires_in`               | Segundos até o token de acesso expirar, no máximo `3600`                                         |
| `scope`                    | Sempre `workspace:inference`                                                                     |
| `connection_id`            | O ID da conexão, por exemplo `ocon_EXAMPLE`. Somente a concessão `authorization_code` o retorna. |
| `refresh_token`            | O token de atualização da conexão. Retornado somente quando o cliente aprovou `offline_access`.  |
| `refresh_token_expires_in` | Segundos 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

## 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](https://www.rfc-editor.org/rfc/rfc7009) e também aceita IDs de conexão e de perfil de usuário.

Envie os parâmetros em [Autenticação de cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-authentication) 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âmetro         | O que encerra                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `connection_id`   | Uma das conexões do seu app, informada como um ID `ocon_`                                                                            |
| `user_profile_id` | Todas as conexões do seu app em um perfil de usuário, informado como um ID `uprof_`                                                  |
| `token`           | Para 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:

```json
{
  "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

| Item                          | Tempo de vida                                                       |
| ----------------------------- | ------------------------------------------------------------------- |
| `request_uri` do endpoint PAR | 10 minutos, uso único                                               |
| Código de autorização         | 5 minutos, uso único                                                |
| `access_token`                | Até 1 hora                                                          |
| `refresh_token`               | Até 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](https://www.rfc-editor.org/rfc/rfc6749)), exceto `user_profile_already_linked`, que é específico da Anthropic.

| Erro                          | Quando                                                                                                                                                                                                                                                          | O que mostrar ao seu usuário                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied`               | A 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`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#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_error`                | `auth.claude.com` não conseguiu processar a solicitação.                                                                                                                                                                                                        | Peça ao usuário que tente novamente.                                                                                                                                                                                                                                                                                                                                                                                              |
| `user_profile_already_linked` | Somente 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`.

| Erro                          | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`             | Um 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_client`              | `auth.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_scope`               | O escopo solicitado não é permitido para este app ou este tipo de conexão. Para os [tokens de uma conexão de faturamento](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection), 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_grant`               | O 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).                                                                                                                                                                                                                                                                                                                                                    |
| `unauthorized_client`         | Seu 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`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client). Para os [tokens de uma conexão de faturamento](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection), `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_linked` | Somente 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) 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`.

| Erro                  | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`     | Um 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_client`      | `auth.claude.com` não conseguiu autenticar seu app. Para saber o que verificar, consulte `invalid_client` em [Erros dos endpoints PAR e de token](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#errors-from-the-par-and-token-endpoints).                                                                                                                                                                                                           |
| `unauthorized_client` | Seu 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.

| Status | Quando                                                                   | O que fazer                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Um parâmetro é maior que seu limite.                                     | Corrija a solicitação. Não tente novamente.                                                                                                                                                                                                                                                                                                                                                                                         |
| 429    | Muitas solicitações com falha vieram do seu endereço IP.                 | Tente novamente com backoff.                                                                                                                                                                                                                                                                                                                                                                                                        |
| 500    | `auth.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.                                                                                                                                                                                                                                                                                                                  |
| 501    | A Anthropic não habilitou este endpoint para sua organização.            | Não tente novamente. Entre em contato com sua equipe de conta da Anthropic.                                                                                                                                                                                                                                                                                                                                                         |
| 503    | A 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). 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.

| Status | Tipo e código de erro                                      | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | `invalid_request_error`                                    | A 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.                                                                                                                                                                                                                                                                                                                                                      |
| 400    | `invalid_request_error`, `user_profile_required`           | `bill_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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 400    | `invalid_request_error`, sem código de erro                | A 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`.                                                                                                                                                                                                                                                                                                                                                                                                      |
| 401    | `authentication_error`                                     | A 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.                                                                                                                                                    |
| 402    | `billing_error`, `linked_organization_spend_limit_reached` | A 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#expected-errors) para Linked billing informa onde cada um é definido e o que alterar.                                                                                                                  |
| 402    | `billing_error`, `linked_organization_billing_unavailable` | A 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.                                                                                                                                                                                                                                                                                                                                                       |
| 403    | `permission_error`, sem código de erro                     | A Anthropic não cobra sua organização diretamente, portanto não pode cobrar clientes em seu nome.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 403    | `permission_error`, `user_profile_not_billable`            | O 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`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable) informa o que verificar em cada caso. |
| 503    | `overloaded_error`                                         | A 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ão                                                                             | Onde se aplica                                                                                                                                                         |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [OAuth 2.0 (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749)                     | Fluxo de código de autorização, endpoint de token e respostas de erro                                                                                                  |
| [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)                          | Obrigatório com `S256` em todas as solicitações de autorização                                                                                                         |
| [Pushed authorization requests (RFC 9126)](https://www.rfc-editor.org/rfc/rfc9126) | Obrigatório para Linked billing.                                                                                                                                       |
| [Revogação de token (RFC 7009)](https://www.rfc-editor.org/rfc/rfc7009)            | 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)](https://www.rfc-editor.org/rfc/rfc7523)   | 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.

| Termo                              | Significado                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Organização Claude                 | Uma conta de organização na Anthropic. Sua empresa tem uma, assim como cada cliente que vincula sua organização para faturamento.                                                                                                                                                                                                                                                                                                                                                    |
| Administrador                      | Um membro de uma organização Claude com a função Admin ou Faturamento.                                                                                                                                                                                                                                                                                                                                                                                                               |
| App OAuth                          | O 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ão                    | Quem aprova uma conexão: um administrador em nome de uma organização inteira (`organization_shared`, para Linked billing).                                                                                                                                                                                                                                                                                                                                                           |
| Provedor de identidade             | O 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 assertion                   | Um 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 Federation       | O 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 descoberta            | O documento OIDC que lista o emissor, os endpoints e as chaves de assinatura da Anthropic.                                                                                                                                                                                                                                                                                                                                                                                           |
| Perfil de usuário                  | Um 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ço                   | Uma 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ão            | O 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](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). |
