---
title: Linked billing
url: https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections
description: Permita que seus clientes vinculem a organização da Claude Platform deles ao seu app com OAuth e fature o uso do Claude na organização do cliente.
---

<Warning>
  O 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 de Serviço](https://www.anthropic.com/legal/service-specific-terms). Endpoints, parâmetros e comportamento podem mudar durante o beta. Ele pode não ser adequado para uso em produção.
</Warning>

O Linked billing permite que seus clientes paguem pelo uso do Claude no seu app por meio da própria organização Claude deles. Um cliente vincula sua organização Claude ao seu app uma única vez. A API chama esse vínculo de “connection” (conexão). Depois que o cliente faz o vínculo, você escolhe, em cada solicitação à Claude API, se quem paga é o cliente ou você. O cliente pode desvincular seu app a qualquer momento. Se uma solicitação que você marcar para o cliente não puder ser faturada a ele, a Claude API a recusa em vez de faturar você.

Este guia é para desenvolvedores cujos usuários do app são principalmente clientes da Claude Platform. Você adiciona um botão “Link your Claude organization” ao seu app. Seu usuário clica nele, faz login no Claude e aprova que seu app fature a organização Claude dele pelas solicitações à Claude API que o cliente orienta você a fazer. Em seguida, seu app adiciona um campo [`billing_policy`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) às solicitações pagas pelo cliente.

## Clientes e endpoints elegíveis

**Clientes elegíveis:** Um cliente só pode ser faturado dessa forma se a organização dele na Claude Platform pagar diretamente à Anthropic pelo uso da API. Tanto créditos pré-pagos quanto cobrança por fatura contam. Organizações faturadas por meio de um marketplace de nuvem (AWS, Google Cloud ou Azure) não podem ser faturadas por meio desta integração. O mesmo vale para organizações que têm apenas um plano de assinatura do Claude. As solicitações para elas são recusadas com 403 `user_profile_not_billable`.

As solicitações são executadas na sua organização, portanto seus “rate limits” (limites de taxa), acesso a modelos, nível de serviço, retenção de dados e chaves de criptografia se aplicam. Os próprios acordos de dados do seu cliente não se aplicam a essas solicitações, incluindo [“zero data retention” (retenção zero de dados), ou ZDR](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope), um “business associate agreement” (Acordo de Associado de Negócios), ou BAA, e “customer-managed encryption keys” (chaves de criptografia gerenciadas pelo cliente), ou CMEK. Não vincule clientes que precisem de cobertura HIPAA, FERPA ou CMEK para esse uso.

**Endpoints compatíveis:** `billing_policy` é compatível com:

* `/v1/messages`
  * Limitação conhecida: uma solicitação que fatura seu cliente (`bill_to: "user_profile"`) não pode usar [recursos faturáveis de execução de código](https://platform.claude.com/docs/pt-BR/about-claude/pricing#code-execution-tool) (a API retorna um 400), portanto envie essas solicitações com `bill_to: "self"` ou sem `billing_policy`.
* `/v1/chat/completions`
* `/v1/messages/count_tokens` aceita o campo `billing_policy` e o ignora, para que você possa contar tokens no corpo exato que está prestes a enviar.

O [Message Batches](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) (`/v1/messages/batches`) ainda não oferece suporte ao faturamento do seu cliente. Envie as solicitações em um lote com `bill_to: "self"` ou sem `billing_policy`, e elas serão faturadas a você normalmente. Uma solicitação em um lote que define `bill_to: "user_profile"` é recusada: seu resultado é `errored` com um `invalid_request_error`, nem você nem seu cliente são faturados por ela, e as outras solicitações do lote são executadas normalmente.

Para solicitar suporte em outro endpoint, entre em contato com a equipe da sua conta na Anthropic.

### Quais créditos podem pagar

Nem todo crédito pode pagar por uma solicitação que uma plataforma fatura a um cliente. O que pode pagar depende da organização que é faturada: o cliente, se você fatura um cliente, ou a sua organização, se uma plataforma fatura você.

O crédito comprado no Claude Console para essa organização pode pagar por essas solicitações. Se essa organização tiver cobrança por fatura, ela é faturada por essas solicitações.

Alguns créditos promocionais da Anthropic não podem pagar por essas solicitações. Entre eles estão os créditos mensais de API que acompanham os planos Claude Max, Ultra e Team. Créditos dos programas de parceiros, de VC e de startups da Anthropic não são elegíveis para pagar por essas solicitações.

Quando nada na conta dessa organização pode pagar por uma solicitação, a Claude API pode recusá-la com um 402. A resposta não informa se a recusa foi causada pela falta de crédito ou por um limite de gastos. Consulte [Erros esperados](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

## Processo de configuração

Você realiza estas três etapas uma única vez. Elas registram seu app na Anthropic. Depois delas, [Qual perfil de usuário vincular](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link) explica uma regra de que você precisa antes de criar perfis de usuário.

### Etapa 1: Criar o app

Crie o app OAuth no Claude Console. Ele é o registro que identifica seu produto para a Anthropic: ele vincula seu URI de redirecionamento a um client ID, e o nome dele é o que seu usuário vê na página de aprovação.

Um membro da sua organização com a função Admin abre a página [apps OAuth](https://platform.claude.com/settings/oauth-apps) no Console e clica em **Create**. Insira o nome do seu app e o URI de redirecionamento (o endereço no seu app para o qual o navegador retorna após a aprovação). Em **What the app can do**, selecione **Bill and link to organizations**.

A página do novo app é aberta. Copie o client ID que o Console mostra para o app. Seu app o envia na Etapa 5, quando solicita uma página de aprovação, na Etapa 6, quando redireciona o navegador, e na Etapa 8, quando troca o código, para que a Anthropic saiba qual app está fazendo a solicitação. O client ID é público. Na aba **Appearance**, defina o nome, a página inicial e a URL do logotipo do seu app.

Na aba **Settings**, **Who can link** mostra **Test users only** para um novo app, que começa em teste. Depois que você [publicar seu app](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#publish-your-app) e ele estiver ativo, a configuração mostra **Any Claude user**.

<Note>
  Uma organização pode registrar vários apps OAuth, por exemplo, um para produção e outro para testes. Cada app tem suas próprias conexões: um cliente que se vincula ao seu app de teste não fica vinculado ao seu app de produção. Mantenha o Linked billing em um único app de produção durante toda a vida útil da sua integração.
</Note>

### Etapa 2: Configurar a autenticação do cliente

Configure como seu back-end comprova para `auth.claude.com` que as solicitações dele vêm do seu app. Isso substitui um client secret: a Anthropic não emite client secrets para apps OAuth.

Na aba **Client authentication** do app, selecione seu **Identity provider** (o emissor que assina os tokens do seu back-end). Para adicionar um, clique em **Register a new issuer**. Em seguida, defina um **Subject pattern**, ou condições de claims em **Advanced match options**, que esses tokens devem atender. Depois que você salvar, a aba mostra o audience esperado. A claim `aud` da sua client assertion deve ser exatamente esse valor.

<Note>
  Seu app se autentica nos endpoints de PAR, de token e de revogação com uma variação do método `private_key_jwt` (RFC 7523): a cada solicitação, seu back-end envia uma “client assertion” (asserção de cliente), um JWT emitido pelo seu provedor de identidade. `auth.claude.com` verifica a assinatura do token com as chaves registradas para esse emissor e o confere com as condições de subject ou de claims que você definiu aqui. Para as claims que uma client assertion deve conter, consulte [Claims da client assertion](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-assertion-claims).
</Note>

### Etapa 3: Configurar a identidade do seu back-end

Seu back-end precisa de uma identidade própria para chamar a Claude API. Crie duas coisas:

* **Uma “service account” (conta de serviço).** Esta é uma conta não humana na sua organização Claude. Seu back-end se autentica como essa conta ao chamar a Claude API.
* **Uma segunda regra de federação.** Assim como a regra da autenticação do cliente do app na Etapa 2, ela permite que seu back-end se autentique com tokens do seu próprio provedor de identidade.

Para configurá-las no Claude Console, siga o guia [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation).

Em seguida, na aba **Client authentication** do app, selecione essa conta de serviço como a conta de serviço operadora do app. Somente essa conta de serviço está autorizada a enviar solicitações de inferência e a atribuir o faturamento aos perfis de usuário vinculados. Uma conta de serviço pode ser a operadora de apenas um app OAuth.

Por padrão, qualquer solicitação autenticada como essa conta de serviço pode faturar todos os clientes vinculados, definindo o cabeçalho de perfil de usuário e `bill_to` na Messages API. Para obter tokens de autenticação restritos apenas a uma conexão específica, 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). Antes de vincular clientes, [defina um workspace](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) para seu app. A Etapa 8 retorna esse tipo de token para cada cliente e exige que o app especifique um workspace padrão na sua organização no qual a inferência é executada. Se quiser “refresh tokens” (tokens de atualização) para cada conexão, ative também **Offline access** para seu app. Em seguida, solicite `offline_access` no fluxo de autorização, na Etapa 5, antes de vincular clientes.

### Qual perfil de usuário vincular

Um “user profile” (perfil de usuário) é um registro na sua própria organização Claude que representa um dos seus clientes. Cada solicitação que fatura o cliente inclui o ID do perfil, para que a Anthropic saiba qual cliente faturar. Para saber o que mais os perfis fazem, consulte [Perfis de usuário para atribuição a clientes finais](https://platform.claude.com/docs/pt-BR/manage-claude/user-profiles).

Defina qual perfil de usuário representa cada cliente antes de vincular seu primeiro cliente. Dentro de um app, as conexões são de um para um:

* A organização Claude de um cliente pode ser vinculada a apenas um dos seus perfis de usuário.
* Um perfil de usuário pode ser vinculado a apenas uma organização Claude.

A organização Claude do cliente é aquela que o usuário seleciona ao aprovar seu app. Para saber como as equipes de um cliente usam as organizações Claude, pergunte ao cliente. Para aplicar a regra de um para um aos registros dos seus clientes:

* **Várias equipes de um cliente compartilham uma organização Claude:** Use um único perfil de usuário para todas as equipes.
* **Cada equipe tem sua própria organização Claude:** Crie um perfil de usuário para cada organização.

Qualquer perfil de usuário ativo na sua organização pode ser vinculado, desde que a regra de um para um seja respeitada. O vínculo não altera o perfil, seu ID nem seu histórico de uso. Se você vincular um segundo perfil de usuário a uma organização Claude que já está vinculada, a aprovação é recusada: consulte [`user_profile_already_linked`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#user-profile-already-linked).

#### Um perfil de usuário para cada pessoa

Você pode já ter um perfil de usuário para cada pessoa que usa seu produto. Várias dessas pessoas podem trabalhar para um mesmo cliente. Nesse caso, a Anthropic recomenda que você crie mais um perfil de usuário para a organização Claude do cliente e vincule esse perfil.

O ID de perfil a ser enviado depende de quem paga pela solicitação:

* **Solicitações que você fatura ao cliente:** Envie o ID do perfil do cliente. Para também identificar a pessoa em uma solicitação a `/v1/messages`, defina [`metadata.user_id`](https://platform.claude.com/docs/pt-BR/api/messages/create) como um identificador dessa pessoa. Esse identificador é opcional e ajuda a Anthropic a detectar o uso indevido por uma pessoa. Use um valor opaco, e não um nome, um endereço de e-mail ou um número de telefone.
* **Solicitações pelas quais você paga:** Você pode continuar enviando o ID do perfil da própria pessoa.

## Vincular cada cliente

Você realiza as Etapas 4 a 8 para cada cliente que vincula a organização dele. Os trechos de código Python a seguir exigem o Anthropic SDK e algumas importações padrão; consulte [Inicialização dos trechos de código](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#code-snippet-initialization). Os exemplos em outras linguagens e a CLI obtêm suas credenciais do ambiente. Certifique-se de que `ANTHROPIC_API_KEY` não esteja definida, pois seu app precisa se autenticar com Workload Identity Federation.

Adicione um botão “Link your Claude organization” no local em que seus clientes gerenciam faturamento ou integrações no seu produto (para o HTML, as cores e o logotipo do botão, consulte [Exemplos de identidade visual](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/branding-samples#buttons)). Informe a eles que, para fazer o vínculo, precisam ter a função Admin ou Faturamento na organização Claude deles.

Para percorrer as etapas você mesmo primeiro, consulte [Testar como cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).

<Frame>
  ![Diagrama de sequência das Etapas 5 a 8: a solicitação de aprovação, a aprovação do usuário e a troca por um connection ID (ID de conexão)](https://platform.claude.com/docs/pt-BR/images/oauth-apps-billing-connection-flow.svg)
</Frame>

### Etapa 4: Criar um perfil de usuário para o cliente

Crie um perfil de usuário para a organização Claude de cada cliente e armazene o ID do perfil no registro do cliente no seu produto.

Se você já tiver um perfil de usuário para a organização Claude deste cliente, pule esta etapa e use o ID desse perfil. Para decidir qual é esse perfil, consulte [Qual perfil de usuário vincular](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link).

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/user_profiles \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "name": "Example Customer Inc.",
      "external_user_details": {"reference_id": "your-customer-id-123"}
    }'
  ```

  ```bash CLI
  ant user-profiles create \
    --name "Example Customer Inc." \
    --external-user-details.reference-id your-customer-id-123
  ```

  ```python Python
  def create_user_profile(name: str, customer_id: str) -> str:
      profile = client.user_profiles.create(
          name=name,
          external_user_details={"reference_id": customer_id},
      )
      return profile.id  # "uprof_..."


  user_profile_id = create_user_profile("Example Customer Inc.", "your-customer-id-123")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const profile = await client.userProfiles.create({
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  });

  console.log(profile.id); // "uprof_..."
  ```

  ```csharp C#
  AnthropicClient client = new();

  var profile = await client.UserProfiles.Create(
      new()
      {
          Name = "Example Customer Inc.",
          ExternalUserDetails = new() { ReferenceID = "your-customer-id-123" },
      }
  );

  Console.WriteLine(profile.ID);
  ```

  ```go Go
  client := anthropic.NewClient()

  profile, err := client.UserProfiles.New(context.Background(), anthropic.UserProfileNewParams{
  	Name: anthropic.String("Example Customer Inc."),
  	ExternalUserDetails: anthropic.UserProfileExternalUserDetailsParams{
  		ReferenceID: anthropic.String("your-customer-id-123"),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(profile.ID)
  ```

  ```java Java
  import com.anthropic.models.userprofiles.UserProfileCreateParams;
  import com.anthropic.models.userprofiles.UserProfileExternalUserDetailsParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = UserProfileCreateParams.builder()
          .name("Example Customer Inc.")
          .externalUserDetails(UserProfileExternalUserDetailsParams.builder()
              .referenceId("your-customer-id-123")
              .build())
          .build();
      var profile = client.userProfiles().create(params);

      IO.println(profile.id());
  }
  ```

  ```php PHP
  $client = new Client();

  $profile = $client->userProfiles->create(
      name: 'Example Customer Inc.',
      externalUserDetails: ['referenceID' => 'your-customer-id-123'],
  );

  echo $profile->id, PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  profile = client.user_profiles.create(
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  )

  puts(profile.id)
  ```
</CodeGroup>

Se sua organização revende acesso à API, envie também `"access_type": "passthrough"` ao criar este perfil. Estes exemplos omitem `access_type`, o que cria um perfil `application`. Para os dois tipos, consulte [Decidir quem recebe um perfil](https://platform.claude.com/docs/pt-BR/manage-claude/user-profiles#decide-who-gets-a-profile).

A resposta contém o `id` do perfil, por exemplo `uprof_01HV9Z`.

<Note>
  Cada solicitação de criação gera um novo perfil, mesmo com o mesmo `reference_id` (seu próprio ID para o cliente), portanto reutilize o ID armazenado em vez de criar um perfil a cada tentativa de conexão.
</Note>

### Etapa 5: Criar uma URL de pushed authorization request

Crie uma “pushed authorization request” (solicitação de autorização enviada previamente) que faça referência ao perfil de usuário do cliente da Etapa 4. A resposta fornece a você um `request_uri`. Na próxima etapa, você o usa para redirecionar seu usuário à página de aprovação.

Antes de enviar a solicitação, seu back-end cria dois valores aleatórios e os armazena na sessão do navegador e no registro do cliente. Ele usa ambos novamente na Etapa 8:

* Um valor `state`, que permite verificar se o navegador que retorna ao seu app é o mesmo que iniciou esta solicitação.
* Um PKCE code verifier, um segredo que somente seu back-end conhece. A solicitação carrega um hash dele (o code challenge), e a Etapa 8 envia o próprio verifier, para que somente seu back-end possa usar o código que retorna.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/par \
    -H "content-type: application/json" \
    -d '{
      "response_type": "code",
      "client_id": "YOUR_CLIENT_ID",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "scope": "billing:attribution",
      "connection_type": "organization_shared",
      "connection_auth_target": "platform",
      "user_profile_id": "uprof_01HV9Z",
      "state": "RANDOM_STATE",
      "code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
      "code_challenge_method": "S256",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  def push_authorization_request(user_profile_id: str) -> dict:
      state = secrets.token_urlsafe(32)
      code_verifier = secrets.token_urlsafe(64)
      code_challenge = create_s256_code_challenge(code_verifier)

      response = httpx.post(
          f"{AUTH}/v1/oauth/par",
          json={
              "response_type": "code",
              "client_id": CLIENT_ID,
              "redirect_uri": REDIRECT_URI,
              "scope": "billing:attribution",
              "connection_type": "organization_shared",
              "connection_auth_target": "platform",
              "user_profile_id": user_profile_id,
              "state": state,
              "code_challenge": code_challenge,
              "code_challenge_method": "S256",
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          },
      )
      response.raise_for_status()  # on an error, do not redirect the browser

      return {
          "state": state,
          "code_verifier": code_verifier,
          "request_uri": response.json()["request_uri"],  # valid for 600 seconds
          "user_profile_id": user_profile_id,
      }


  par = push_authorization_request(user_profile_id)
  ```
</CodeGroup>

`auth.claude.com` responde com HTTP 201, um `request_uri` e `expires_in` de 600 segundos. O `request_uri` identifica a página de aprovação desta solicitação. O `scope` deve ser exatamente `billing:attribution` ou `billing:attribution offline_access`. Consulte [Escopos para uma conexão de faturamento](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection) para mais detalhes. Os exemplos enviam `billing:attribution`. Se seu app não tiver esse escopo, adicione-o em **Billing** na aba **Permissions** do app.

`connection_auth_target` deve ser `platform`: as solicitações de inferência são executadas na sua própria organização, autenticadas como a conta de serviço operadora, mas podem faturar o cliente.

`user_profile_id` deve ser o ID de um perfil de usuário ativo na sua organização. Se a pushed authorization request falhar, `auth.claude.com` retorna uma resposta de erro OAuth ao seu back-end. Nesse caso, não redirecione o navegador.

### Etapa 6: Enviar seu usuário à página de aprovação do Claude

Primeiro, mostre ao seu usuário qual conta no seu produto ele está vinculando e diga a ele que verifique a conta Claude que a página de aprovação mostra. A página mostra qual conta Claude está conectada e permite que o usuário troque para outra. A página de aprovação oferece somente as organizações da conta Claude que estiver conectada no navegador, portanto a conta errada pode vincular a organização errada. Quem paga é a organização que o usuário vincula.

<Note>
  A pessoa que aprova deve ser administradora da organização Claude do cliente: um membro com a função Admin ou Faturamento.
</Note>

Em seguida, redirecione seu usuário ao endpoint de autorização, que mostra uma página de aprovação. Inclua somente seu `client_id` e o `request_uri` da Etapa 5.

```python
def authorize_url(par: dict) -> str:
    query = urlencode({"client_id": CLIENT_ID, "request_uri": par["request_uri"]})
    return f"{AUTH}/oauth/authorize?{query}"


redirect_to = authorize_url(par)  # answer the click with a 302 to this URL
```

### Etapa 7: O usuário aprova

Seu app não faz nada nesta etapa. O usuário percorre estas etapas em `auth.claude.com`:

1. O usuário faz login no Claude, a menos que o navegador já esteja conectado.

2. A página de aprovação mostra as seguintes telas, cada uma com o nome do seu app. Para saber o que o usuário faz em cada tela, consulte [Vincular](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connecting).

   1. **Select an organization**, somente se o usuário puder escolher entre organizações.
   2. **How billing works**.
   3. **Set a monthly spend limit**.
   4. Uma última tela com um botão **Link and authorize**.

3. Quando o usuário clica em **Link and authorize**, `auth.claude.com` envia o navegador de volta ao seu app. A página de aprovação não mostra nenhuma tela de confirmação.

Se o usuário cancelar ou não puder aprovar, nenhuma conexão é feita: consulte [Se o vínculo não for concluído](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

<Note>
  A conexão pertence à organização Claude inteira, e não ao usuário que a aprovou. Se esse usuário sair da organização, a conexão permanece ativa. Qualquer administrador da organização do cliente ou da sua pode encerrar a conexão a qualquer momento, e seu back-end também pode.
</Note>

### Etapa 8: Tratar o callback e salvar a conexão

Após a aprovação, `auth.claude.com` envia o navegador de volta ao seu URI de redirecionamento com um código de uso único e seu valor `state`. Essa solicitação ao seu URI de redirecionamento é chamada de “callback” (retorno de chamada). Seu back-end troca o código por um ID de conexão e o armazena no registro do cliente. Isso conclui a conexão. O callback pode trazer um parâmetro `error` e nenhum código. Nesse caso, nenhuma conexão foi feita: consulte [Se o vínculo não for concluído](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

Verifique se o `state` corresponde ao valor que você armazenou na Etapa 5 e, em seguida, troque o código imediatamente a partir do seu back-end, junto com o PKCE code verifier. O código é de uso único e expira após 5 minutos.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d '{
      "grant_type": "authorization_code",
      "code": "AUTH_CODE",
      "code_verifier": "ORIGINAL_CODE_VERIFIER",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "client_id": "YOUR_CLIENT_ID",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  def handle_callback(par: dict, params: dict) -> str:
      if not secrets.compare_digest(
          params.get("state", "").encode(), par["state"].encode()
      ):
          raise ValueError("state does not match")
      if "error" in params:  # for example access_denied
          raise PermissionError(params["error"])
      code = params["code"]  # single-use, expires after 5 minutes
      response = httpx.post(
          f"{AUTH}/v1/oauth/token",
          json={
              "grant_type": "authorization_code",
              "code": code,
              "code_verifier": par["code_verifier"],
              "redirect_uri": REDIRECT_URI,
              "client_id": CLIENT_ID,
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          },
          timeout=10,  # a response that times out loses the tokens in it
      )
      response.raise_for_status()
      tokens = response.json()
      # Para usar os tokens da conexão, armazene tokens["access_token"], seu tempo
      # de expiração (de tokens["expires_in"]) e, com offline_access,
      # tokens["refresh_token"] como segredos aqui: o código não pode ser trocado de novo.
      # "ocon_..."; armazene-o no registro do cliente
      return tokens["connection_id"]
  ```
</CodeGroup>

A resposta contém o ID da conexão e [o “access token” (token de acesso) da conexão](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection), que pode autenticar e faturar o cliente que aprovou. Se o cliente aprovou `offline_access`, a resposta também contém um refresh token. Armazene o `connection_id` e os tokens agora: a troca retorna os tokens apenas uma vez. [Armazenar os tokens](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) descreve a resposta.

Os exemplos desta página que chamam a Claude API se autenticam como a conta de serviço da Etapa 3, e não com um token desta resposta. [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) explica como usar o token no lugar dela.

A resposta não identifica qual organização Claude o usuário vinculou.

Uma conexão concluída não garante que a Anthropic possa faturar o cliente. Por exemplo, a organização do cliente pode não ser um dos [clientes elegíveis](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). Consulte [Atualizar chamadas ao Claude](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) e [Erros esperados](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#expected-errors) para saber como a Claude API verifica isso. Por causa dessa verificação, redija sua mensagem de sucesso como “vinculado” em vez de “faturamento ativo”.

Se a troca for recusada com `unauthorized_client`, 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).

<Note>
  Um usuário pode aprovar novamente para um perfil de usuário que já está vinculado. O resultado depende dos escopos:

  * Aprovado novamente para o mesmo perfil de usuário e os mesmos escopos: a conexão permanece, e a resposta de token retorna o mesmo `connection_id` e um novo token de acesso. A exceção é uma conexão com `billing:attribution offline_access`: a troca do código retorna `invalid_grant`, a conexão permanece como estava, e [Vincular um cliente novamente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again) explica o que fazer.
  * Aprovado novamente para o mesmo perfil de usuário com outros escopos, por exemplo `billing:attribution offline_access` depois de `billing:attribution`: a troca do novo código cria uma nova conexão com um novo `connection_id`, que substitui a anterior. Os tokens de uma conexão `billing:attribution` anterior são revogados. Armazene o novo `connection_id` no lugar do anterior. Se a troca falhar com uma resposta 5xx, execute novamente as Etapas 5 a 8. [Escopos para uma conexão de faturamento](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection) explica quando você precisa disso.
  * Depois que uma conexão é revogada, você pode vincular o mesmo perfil de usuário novamente.
</Note>

### Testar como cliente

Para verificar se o vínculo funciona, vincule uma organização sua. Primeiro, você precisa destes itens:

* Uma segunda organização Claude sua para atuar como cliente. Você não pode vincular seu app à organização proprietária dele. A página de aprovação não oferece essa organização. A segunda organização precisa ser um dos [clientes elegíveis](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints).
* Uma pessoa com a função Admin ou Faturamento nessa organização para aprovar o vínculo.
* Até que seu app esteja ativo, essa pessoa precisa estar na lista **Test users** do seu app. A lista fica na aba **Settings** do app, em **Who can link**. Adicione a pessoa pelo endereço de e-mail da conta Claude dela e clique em **Save changes**. [Enquanto seu app está em teste](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing) informa o teto de gastos que se aplica. Remover alguém da lista encerra os vínculos que essa pessoa aprovou.

Em seguida, execute as Etapas 4 a 8 e peça a essa pessoa que aprove na Etapa 7. Quando o vínculo for feito, o perfil de usuário mostrará **Linked** na sua página [User profiles](https://platform.claude.com/user-profiles) no Console.

### Se o vínculo não for concluído

Quando o usuário não conclui a aprovação, ou quando `auth.claude.com` a recusa, nenhuma conexão é feita. Estas entradas tratam dos resultados específicos do Linked billing. Para todos os outros erros, consulte [Erros](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#errors) na Referência de OAuth.

#### Seu URI de redirecionamento recebe `error=access_denied`

A solicitação também traz seu valor `state`. Seu URI de redirecionamento recebe esse erro em casos como estes:

1. O usuário clica em **Cancel** em qualquer tela de aprovação.

2. A página de aprovação não tem nenhuma organização para oferecer ao usuário, e o usuário clica no botão que retorna ao seu app. Por exemplo:

   * O usuário não tem a função Admin ou Faturamento em nenhuma organização da Claude Platform.
   * A única organização do usuário é a proprietária do seu app. Consulte [Testar como cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).
   * O perfil de usuário já está vinculado a outra organização Claude, e o usuário não tem a função Admin ou Faturamento nessa organização.
   * Até que seu app esteja ativo, o usuário não está na lista **Test users** dele.

Em cada caso desta lista, o `error_description` indica `the user declined the request`, portanto ele não permite distingui-los.

Mais uma causa está nas configurações do seu app. Se seu app estiver ativo e **Who can link** mostrar apenas sua organização, ninguém de fora da sua organização poderá vincular o app. Selecione **Any Claude user** e clique em **Save changes**.

Informe ao usuário que o vínculo não foi concluído e não presuma que ele recusou. Peça a ele que verifique com qual conta Claude fez login e qual é a função dele na organização que deseja vincular. Um `request_uri` não pode ser usado novamente depois que o usuário cancela ou retorna, portanto, para permitir que o usuário tente novamente, recomece a partir da Etapa 5.

#### Seu app recebe `user_profile_already_linked`

A organização Claude do cliente já está vinculada ao seu app por meio de outro dos seus perfis de usuário. `auth.claude.com` pede que o usuário entre em contato com você. Se o usuário retornar ao seu app, seu URI de redirecionamento recebe `error=user_profile_already_linked` e seu valor `state`. O endpoint de token também pode retornar esse erro quando você troca o código na Etapa 8. Isso acontece, por exemplo, quando a organização foi vinculada por meio de outro perfil de usuário nesse meio-tempo.

A Anthropic não informa qual organização Claude um cliente vincula, portanto você não consegue ver isso com antecedência. A pushed authorization request na Etapa 5 é bem-sucedida, e `auth.claude.com` recusa a conexão somente quando o usuário aprova.

O erro não indica qual perfil de usuário detém a conexão. O detentor mais provável é outro perfil vinculado deste cliente. A Anthropic não mostra a qual organização um perfil está vinculado, então confirme com o cliente antes de agir. Se esse perfil detiver a conexão, faça uma das seguintes ações:

* Nas solicitações que você fatura a esse cliente, envie o ID desse perfil de usuário.
* Encerre essa conexão, conforme descrito em [Desvincular um cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer) e, em seguida, execute novamente as Etapas 5 a 8 com o perfil de usuário que foi recusado.

Se nenhum dos perfis deste cliente estiver vinculado, o usuário pode ter selecionado uma organização que pertence a outro dos seus clientes. Recomece a partir da Etapa 5 e peça ao usuário que verifique qual organização ele seleciona.

#### Seu URI de redirecionamento não recebe nada

Seu app não consegue detectar estes dois casos:

* O usuário fecha a página de aprovação.
* O `request_uri` expirou ou já foi usado. A página de aprovação então mostra um erro e não envia o navegador de volta ao seu app.

Se o usuário voltar ao seu produto sem um callback, recomece a partir da Etapa 5. Um `request_uri` que não foi usado expira 10 minutos após você criá-lo.

#### A troca do código retorna `unauthorized_client`

Seu app não está configurado para esta solicitação. Para um problema de workspace, o `error_description` indica a causa. Para uma conta de serviço operadora ausente, ele indica apenas `the client is not registered for this grant`. A recusa não consome o código, então você pode trocar o mesmo código novamente até que ele expire. Primeiro, verifique estes itens no Claude Console:

| Verificação                                       | Onde                                                                                                                                                           | Correção                                                                                                    |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| O app tem uma conta de serviço operadora          | **Operator service account** na aba **Client authentication** do app                                                                                           | Selecione uma e clique em **Save**. A Etapa 3 explica como configurar uma.                                  |
| O workspace do app não está ausente nem arquivado | [Configurar seu app](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) | Escolha um workspace. Enquanto o app não tiver nenhum, a troca também é recusada com `unauthorized_client`. |

Uma conta de serviço salva pode levar um ou dois minutos para chegar a `auth.claude.com`, então, se a troca for recusada novamente, aguarde esse tempo e tente de novo. Se o código já tiver expirado até lá, peça ao usuário que aprove novamente (Etapas 5 a 8). Para as causas que `error_description` indica para os tokens de uma conexão, consulte [Armazenar os tokens](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) e [Atualizar os tokens](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).

Em qualquer outro caso, entre em contato com a equipe da sua conta na Anthropic. Faça o mesmo se o Console informar que a conta de serviço não existe mais.

### Publicar seu app

Até que seu app esteja ativo, somente as pessoas na lista **Test users** dele podem vinculá-lo, portanto seus clientes não podem. Para publicar o app, clique em **Publish app** na página do app no Claude Console. Uma caixa de diálogo é aberta.

* Se sua organização tiver cobrança por fatura, o app fica ativo assim que você confirmar nessa caixa de diálogo.
* Caso contrário, você primeiro comprova nessa caixa de diálogo que controla o domínio do app e, em seguida, a Anthropic analisa o app.

**A comprovação de domínio:** O domínio é o domínio da página inicial do seu app. Todo URI de redirecionamento deve estar nesse domínio ou em um subdomínio dele, exceto um em `localhost`, `127.0.0.1` ou `[::1]`. A comprovação é um registro DNS TXT. Alterações de DNS podem levar até 48 horas, então comece antes de precisar que os clientes façam o vínculo. Se sua organização já tiver comprovado um domínio que abranja a página inicial e esses URIs de redirecionamento, a caixa de diálogo pula a comprovação. Um domínio comprovado abrange seus subdomínios.

Você confirma na última etapa da caixa de diálogo. Se essa etapa mostrar uma caixa de seleção para aceitar os Linked Billing Terms, marque-a. Em seguida, clique em **Publish app** na caixa de diálogo.

**A análise:** Durante a análise, o status do app no Console exibe **In review**. O app fica ativo quando a Anthropic o aprova. Se a Anthropic não o aprovar, o status exibe **Not approved**, e você não pode publicar o app novamente por conta própria. Para perguntar sobre a decisão, entre em contato com o suporte.

A menos que sua organização tenha cobrança por fatura, uma alteração no nome, no logotipo, na página inicial ou nos URIs de redirecionamento de um app ativo envia o app de volta para análise. Os clientes que já estão vinculados permanecem vinculados e mantêm o teto que salvaram. Até que a Anthropic aprove a alteração, somente as pessoas na lista **Test users** podem vincular o app.

## Atualizar chamadas ao Claude

Envie o cabeçalho `anthropic-user-profile-id` em cada chamada a `/v1/messages` e `/v1/chat/completions` para um cliente vinculado. Em uma solicitação que você fatura ao cliente, o valor do cabeçalho é o ID do perfil de usuário que detém a conexão desse cliente. As chamadas que definem `billing_policy` também devem enviar o cabeçalho beta `user-profiles-billing-2026-10-01`.

Cada solicitação para um cliente vinculado é faturada ao cliente ou a você, e você escolhe qual em cada solicitação. Os exemplos a seguir mostram ambos os casos.

[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) descreve outra forma de autenticar as solicitações de um cliente: um token de acesso que pode faturar somente esse cliente. Em `/v1/messages` e `/v1/chat/completions`, uma solicitação com esse tipo de token não pode ser faturada a você. Ela é faturada a esse cliente, mesmo sem `billing_policy` ou o cabeçalho `anthropic-user-profile-id`, quando esses forem opcionais: consulte a nota em [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). Se ela indicar outro perfil de usuário ou definir `bill_to: "self"`, ela é recusada. Nunca use um desses tokens para uma solicitação que você paga.

### Seu cliente paga

Adicione `billing_policy` com `bill_to: "user_profile"` ao corpo da solicitação e envie o cabeçalho beta de faturamento e o cabeçalho do ID do perfil.

<Warning>
  Verifique se o cabeçalho indica o perfil do cliente a que a solicitação se destina. Por padrão, a própria credencial da sua conta de serviço operadora pode faturar todos os clientes vinculados por meio deste app. Se uma solicitação com essa credencial indicar outro perfil vinculado por meio deste app, a Anthropic fatura a organização desse perfil, e nenhum erro avisa você. O [token de acesso de uma conexão](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) pode faturar somente o próprio cliente.
</Warning>

Defina `bill_to: "user_profile"` apenas nas solicitações que o cliente orienta você a fazer: o uso do Claude que o cliente e os usuários dele geram no seu produto. Não cobre de um cliente o seu próprio uso, como testes, avaliações ou trabalho para outros clientes. A Claude API não consegue verificar isso por você, então essa é sua responsabilidade.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: user_profile
  YAML
  ```

  ```python Python
  def message_billed_to_user(user_profile_id: str, prompt: str) -> BetaMessage:
      return client.beta.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": prompt}],
          betas=[BILLING_BETA],
          extra_headers={"anthropic-user-profile-id": user_profile_id},
          extra_body={
              "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
          },
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "user_profile" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy ainda não está nos tipos do SDK
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "user_profile" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "user_profile",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "user_profile")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'user_profile'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "user_profile" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

Se a solicitação for recusada, consulte [Erros esperados](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

### Você paga

Para pagar você mesmo, omita completamente o `billing_policy` (nesse caso, o cabeçalho beta de faturamento é opcional):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}'
  ```

  ```python Python
  def message_billed_to_you(user_profile_id: str, prompt: str) -> Message:
      return client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": prompt}],
          user_profile_id=user_profile_id,
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  });

  console.log(message.content);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var message = await client.Messages.Create(
      new MessageCreateParams
      {
          Model = Model.ClaudeSonnet5_5,
          MaxTokens = 1024,
          Messages = [new UserMessageParam { Content = "Hello, Claude" }],
          UserProfileID = "uprof_01HV9Z",
      }
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
  	},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.models.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .userProfileId("uprof_01HV9Z")
          .build();
      var message = client.messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      userProfileID: 'uprof_01HV9Z',
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  )

  puts(message.content)
  ```
</CodeGroup>

ou use `bill_to: "self"`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "self"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: self
  YAML
  ```

  ```python Python
  def message_billed_to_self(user_profile_id: str, prompt: str) -> BetaMessage:
      return client.beta.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": prompt}],
          betas=[BILLING_BETA],
          extra_headers={"anthropic-user-profile-id": user_profile_id},
          extra_body={"billing_policy": {"type": "billing_policy", "bill_to": "self"}},
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "self" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy ainda não está nos tipos do SDK
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "self" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "self",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "self")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'self'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "self" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

## Tokens OAuth para cada conexão

Seu back-end chama a Claude API como a conta de serviço operadora do seu app (Etapa 3). Por padrão, qualquer solicitação autenticada como essa conta de serviço pode faturar todos os clientes vinculados, passando um cabeçalho de ID de perfil de usuário e incluindo `bill_to` nas solicitações à Messages API. Esse padrão é chamado de “operator-only tokenless authentication” (autenticação sem token exclusiva do operador).

Para lidar com implantações single-tenant do seu produto, ou com ambientes sandbox controlados pelo cliente, você pode obter tokens OAuth de acesso e de atualização vinculados à conexão, em vez de usar a autenticação sem token exclusiva do operador.

Para cada conexão, a troca de código na Etapa 8 retorna o próprio token de acesso dessa conexão. O token se autentica como sua conta de serviço operadora, mas só pode faturar o cliente dessa conexão. Ele expira em até 1 hora.

Para autenticar cada conexão separadamente:

* **Use o acesso offline.** Ative [**Offline access**](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) para seu app e solicite `offline_access` na Etapa 5. Cada conexão passa então a receber também um refresh token, que seu back-end usa para solicitar novos tokens de acesso. Sem ele, o cliente precisa aprovar novamente para fornecer a você um novo token de acesso: execute novamente as Etapas 5 a 8 com o mesmo `scope`.
* **Defina um workspace padrão.** [Escolha um workspace](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) na sua organização no qual as solicitações com esses tokens serão executadas.
* **Opcionalmente, desative a autenticação sem token exclusiva do operador.** Por padrão, você ainda pode faturar um cliente vinculado como sua conta de serviço operadora (passando um cabeçalho de perfil de usuário e `bill_to`), mesmo depois que o token de acesso do cliente expirar. Depois que você [desativar a autenticação somente do operador](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), toda solicitação que fatura um cliente deve se autenticar com o token de acesso desse cliente.
* **Use `billing:attribution`.** Somente esse escopo fornece a uma conexão seus próprios tokens. Você ainda pode faturar um cliente vinculado como sua conta de serviço operadora, como com `org:billing_attribution`, que está descontinuado. Consulte [Escopos para uma conexão de faturamento](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection).

### Configurar seu app

As solicitações com o token de acesso de uma conexão são executadas em um workspace da sua organização. Todo app precisa de um, mesmo que você não use esses tokens: enquanto seu app não tiver um workspace, a troca de código na Etapa 8 é recusada com `unauthorized_client`.

Um membro da sua organização com a função Admin abre a aba **Client authentication** do app no Console. Abaixo da conta de serviço operadora, localize **Default workspace for platform auth mode OAuth tokens** (a configuração `connection_token_workspace_id` do app) e clique em **Choose workspace**. Selecione um workspace do qual a conta de serviço operadora (Etapa 3) seja membro. O workspace não pode estar arquivado.

Para obter refresh tokens, ative **Offline access** na aba **Permissions** do app. Uma alteração nos escopos do app leva alguns minutos para chegar a `auth.claude.com`.

<Note>
  Arquivar o workspace padrão revoga todos os tokens executados nele, e isso não pode ser desfeito. Para mudar para outro workspace, defina o novo e aguarde alguns minutos. Uma atualização feita antes que a alteração chegue a `auth.claude.com` pode retornar tokens que ainda são executados no workspace anterior. Em seguida, atualize todas as conexões que têm um refresh token e só então arquive o workspace anterior. Se você arquivar um workspace primeiro, pare de atualizar as conexões dele antes de definir outro: uma atualização posterior encerra a conexão.

  Não altere nem arquive a conta de serviço operadora do app enquanto houver um cliente vinculado. Depois que você a alterar ou arquivar, `auth.claude.com` recusa todas as atualizações, e os tokens que você tem logo deixam de faturar os clientes. Cada cliente cujos tokens você usa precisará então fazer o vínculo novamente: para obter ajuda, [entre em contato com o suporte](https://support.claude.com/en/articles/9015913-how-to-get-support).
</Note>

### Escopos para uma conexão de faturamento

Na Etapa 5, envie `scope` como `billing:attribution`. Para também obter um “refresh token” (token de atualização), envie `billing:attribution offline_access`.

Para alterar os escopos de um cliente que já está vinculado, por exemplo para adicionar `offline_access`, execute novamente as Etapas 5 a 8 com o perfil de usuário existente do cliente e o novo `scope`. Você não precisa desvincular antes. A troca do código retorna um novo `connection_id`, e a nova conexão substitui a anterior. Consulte a nota na Etapa 8.

Um app pode ter `billing:attribution` e o descontinuado `org:billing_attribution` ao mesmo tempo. Você adiciona `billing:attribution` em **Billing** na aba **Permissions** do app. Se você remover `org:billing_attribution` ali, não poderá adicioná-lo novamente. Uma conexão que um cliente aprovou com `org:billing_attribution` continua faturando por meio da sua conta de serviço operadora até que a conexão seja encerrada ou que você [desative a autenticação somente do operador](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication).

### Armazenar os tokens

A troca do código retorna os tokens apenas uma vez, portanto armazene-os na Etapa 8. A resposta contém `access_token`, `expires_in` (no máximo 1 hora, em segundos) e `connection_id`. Se o cliente aprovou `offline_access`, ela também contém `refresh_token` e `refresh_token_expires_in`. Um refresh token dura no máximo 1 ano, e uma atualização não estende esse prazo. Depois disso, [vincule o cliente novamente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

Armazene os tokens e seus horários de expiração em um cofre de segredos que somente o serviço que faz a atualização possa ler.

Se a troca for recusada com `unauthorized_client`, `error_description` informa a causa, como um workspace ausente ou arquivado. O código não é consumido: corrija a causa e envie o mesmo código novamente antes que ele expire.

### Chamar o Claude com o token de acesso de uma conexão

<Note>
  Durante o beta, pergunte à equipe da sua conta na Anthropic se as solicitações à Claude API com o token de acesso de uma conexão estão habilitadas para sua organização. Enquanto não estiverem, todas essas solicitações falham, seja o que for que elas enviem. Pergunte também se o cabeçalho `anthropic-user-profile-id` e `billing_policy` são opcionais. Enquanto não forem, envie toda solicitação a `/v1/messages` e `/v1/chat/completions` que use o token de acesso de uma conexão conforme mostrado em [Seu cliente paga](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#your-customer-pays), com o cabeçalho, `bill_to: "user_profile"` e o cabeçalho beta de faturamento.
</Note>

Envie o token de acesso da conexão como um “bearer token” (token de portador) no cabeçalho `Authorization`, no lugar da própria credencial da sua conta de serviço operadora. Não envie um cabeçalho `x-api-key`. No Anthropic SDK, passe o token como `auth_token` (typescript, php: `authToken`; java: `.authToken()`; csharp: `AuthToken`; go: `option.WithAuthToken()`), ou defina a variável de ambiente `ANTHROPIC_AUTH_TOKEN`.

Em `/v1/messages` e `/v1/chat/completions`, a solicitação é faturada ao cliente dessa conexão. O cabeçalho `anthropic-user-profile-id` e `billing_policy` são opcionais. Você precisa do cabeçalho beta de faturamento somente com `billing_policy`.

Nesses dois endpoints, você não pode pagar por uma solicitação com esse token. Use o token somente nesses dois endpoints, em `/v1/messages/count_tokens` e nos endpoints de Models. Envie todas as outras solicitações, e todas as solicitações pelas quais você paga, como sua conta de serviço operadora, a partir do seu próprio back-end. Isso inclui uma solicitação que usa [recursos faturáveis de execução de código](https://platform.claude.com/docs/pt-BR/about-claude/pricing#code-execution-tool), que não podem faturar um cliente.

A Claude API recusa estas solicitações:

* `400 invalid_request_error`, sem código de erro: a solicitação indicou outro perfil de usuário ou definiu `bill_to: "self"`.
* `403 permission_error`, sem código de erro: a solicitação foi enviada a um endpoint do [Message Batches](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing).
* `401 authentication_error`: o token expirou, uma atualização o substituiu ou a conexão dele foi encerrada. Depois que uma conexão é encerrada, a resposta também pode ser `403 user_profile_not_billable`.

### Atualizar os tokens

Para renovar o token de acesso de uma conexão, envie o refresh token dela ao endpoint de token, `https://auth.claude.com/v1/oauth/token`, com a [autenticação do cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#client-authentication) do seu app. Não envie um parâmetro `scope`.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d @- <<JSON
  {
    "grant_type": "refresh_token",
    "refresh_token": "$CONNECTION_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "$CLIENT_ASSERTION"
  }
  JSON
  ```

  ```python Python
  connection_locks: defaultdict[str, threading.Lock] = defaultdict(threading.Lock)


  def error_body(response: httpx.Response) -> dict:
      try:
          body = response.json()
      except ValueError:
          return {}
      return body if isinstance(body, dict) else {}


  def is_lost(response: httpx.Response) -> bool:
      """True for a 5xx response that can follow a refresh that took effect."""
      if response.status_code < 500:
          return False
      # Um 503 no formato da Claude API com header retry-after é uma recusa
      # que não usa o refresh token. Qualquer outra resposta 5xx conta como perdida.
      paused = (
          response.status_code == 503
          and error_body(response).get("type") == "error"
          and "retry-after" in response.headers
      )
      return not paused


  def hold_error(connection_id: str, reason: str) -> RefreshOnHold:
      return RefreshOnHold(
          f"Connection {connection_id} is on hold. {reason} Don't send its refresh token"
          ' again: that can end the connection. See "Link a customer again" in the'
          " Linked billing guide."
      )


  def refresh_connection(connection_id: str, *, force: bool = False) -> tuple[str, int]:
      """Refreshes the connection if its access token is close to its expiry.

      Returns the current access token and its expiry time in Unix seconds. Call
      this from your schedule, and pass force=True to refresh a token that isn't
      close to its expiry. Raises RefreshOnHold when the refresh token can't be sent
      again, now and on every later call, and httpx.HTTPStatusError for a refusal
      that keeps the refresh token. After RefreshOnHold for a lost refresh, pause
      your schedule. Resume with one connection, and resume the others only after
      that refresh succeeds or gets a 4xx.
      """
      # Este lock funciona dentro de um processo. Se o serviço tiver réplicas, use um lock
      # compartilhado por todas elas.
      with connection_locks[connection_id]:
          tokens = load_tokens(connection_id)
          if tokens.on_hold:
              raise hold_error(
                  connection_id, "An earlier refresh might have used its refresh token."
              )
          if not force and tokens.expires_at - time.time() > REFRESH_MARGIN_SECONDS:
              return tokens.access_token, tokens.expires_at  # not close to expiry
          request = {
              "grant_type": "refresh_token",
              "refresh_token": tokens.refresh_token,
              "client_id": CLIENT_ID,
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          }
          url = f"{AUTH}/v1/oauth/token"
          # Coloque a conexão em espera antes que o refresh token saia deste processo.
          # Se o processo parar antes de os novos tokens serem salvos, a espera permanece.
          save_tokens(connection_id, replace(tokens, on_hold=True))
          issued_at = int(time.time())
          started = time.monotonic()
          # O httpx não faz retry sozinho. Não adicione retries: um retry tardio encerra a
          # conexão.
          try:
              response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
              lost = is_lost(response)
          except (httpx.ConnectError, httpx.ConnectTimeout):
              # Nenhuma conexão foi feita, então o refresh token nunca saiu deste processo.
              save_tokens(connection_id, tokens)
              raise
          except httpx.TransportError:
              lost = True
          if lost:
              # A primeira requisição pode ter usado o refresh token. Uma segunda requisição
              # só é segura dentro do limite acima, então envie uma imediatamente ou não
              # envie.
              if time.monotonic() - started > SECOND_REQUEST_DEADLINE_SECONDS:
                  raise hold_error(connection_id, "A refresh got no usable answer.")
              try:
                  response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
              except httpx.TransportError:
                  raise hold_error(
                      connection_id, "Two refreshes got no answer."
                  ) from None
              if response.status_code != 200:
                  # Após qualquer resposta que não sejam novos tokens, você não sabe se a
                  # primeira requisição teve efeito, e uma requisição posterior não é segura.
                  raise hold_error(connection_id, "The second refresh failed.")
          if error_body(response).get("error") == "invalid_grant":
              # Expirado, já usado ou a conexão foi encerrada. Enviá-lo de novo
              # pode encerrar a conexão.
              raise hold_error(connection_id, "The refresh returned invalid_grant.")
          if response.status_code != 200:
              # Uma recusa que mantém o refresh token, então retire a espera.
              save_tokens(connection_id, tokens)
              response.raise_for_status()
          body = response.json()
          tokens = ConnectionTokens(
              refresh_token=body["refresh_token"],
              access_token=body["access_token"],
              expires_at=issued_at + body["expires_in"],
              refresh_expires_at=issued_at + body["refresh_token_expires_in"],
          )
          # Se a gravação falhar, tente gravar de novo. Não faça refresh de novo.
          for attempt in range(5):
              try:
                  save_tokens(connection_id, tokens)
                  return tokens.access_token, tokens.expires_at
              except OSError:  # your secret store's error type
                  if attempt < 4:
                      time.sleep(2**attempt)
          # Os novos tokens existem só neste processo, e o refresh token armazenado
          # foi consumido. O registro armazenado ainda está em espera. O erro carrega os novos
          # tokens, para que o chamador possa armazená-los quando o secret store voltar.
          error = hold_error(
              connection_id,
              "The refresh succeeded, but the new tokens could not be saved.",
          )
          error.new_tokens = tokens
          raise error
  ```
</CodeGroup>

A resposta contém um novo `access_token` e um novo `refresh_token`. O refresh token que você enviou é substituído: não o envie novamente, exceto conforme indicado na lista de falhas abaixo. O token de acesso anterior deixa de funcionar em poucos minutos. [Inicialização dos trechos de token OAuth](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#oauth-token-snippet-initialization) define as funções que o exemplo chama.

* Armazene o novo refresh token antes de usar o novo token de acesso.
* Atualize os tokens de cada conexão a partir de um único serviço, uma atualização por vez. Se o serviço tiver réplicas, use um bloqueio compartilhado por todas elas. Um refresh token usado que chega novamente mais de 30 segundos após seu primeiro uso encerra a conexão. Todos os tokens são revogados, o cliente aparece como **Unlinked** e nenhuma credencial pode faturá-lo até que ele faça o vínculo novamente.
* Desative as novas tentativas automáticas para a solicitação de atualização, no seu cliente HTTP e em qualquer proxy.

Se a primeira solicitação com um refresh token falhar:

* A solicitação não conseguiu se conectar: o refresh token não foi enviado. Tente novamente mais tarde.

* Uma conexão interrompida, ou qualquer resposta 5xx diferente do `503` desta lista: você não consegue saber se a solicitação teve efeito, então envie o mesmo refresh token mais uma vez.

  1. Envie-o imediatamente, e somente se tiverem se passado menos de 30 segundos desde que você enviou a primeira solicitação.
  2. Se ele retornar novos tokens, armazene-os e use somente eles. Se a primeira solicitação teve efeito, os tokens dela, que nunca chegaram até você, são revogados.
  3. Se ele retornar qualquer outra coisa ou não receber resposta, ou se os 30 segundos tiverem se passado, não envie esse refresh token novamente. Pare de atualizar essa conexão e [vincule o cliente novamente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* Um tempo limite esgotado: a solicitação ainda pode estar em execução. Não envie esse refresh token novamente. Pare de atualizar essa conexão e [vincule o cliente novamente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* `429`, ou `503` com um cabeçalho `retry-after` e `"type": "error"` no nível superior do corpo: nada foi revogado. Aguarde pelo menos o tempo indicado pelo cabeçalho e envie o mesmo refresh token novamente.

* `unauthorized_client` ou `invalid_client`: nada foi revogado. `error_description` informa a causa, como um workspace ausente, `offline_access` não mais registrado para seu app ou uma client assertion com falha. Corrija-a e envie o mesmo refresh token novamente.

* `invalid_scope`: a solicitação enviou um parâmetro `scope`, ou `billing:attribution` não está mais registrado para seu app. Nada foi revogado. Corrija a causa e envie o mesmo refresh token novamente.

* `invalid_grant`: o refresh token expirou ou já foi usado, a conexão foi encerrada ou a organização do cliente está suspensa. Pare de atualizar essa conexão e siga [Vincular um cliente novamente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again), que começa com uma verificação de suspensão.

Se uma conexão interrompida, uma resposta 5xx ou um tempo limite esgotado fez você parar de atualizar uma conexão, pause também as atualizações das suas outras conexões. Ao retomar, atualize primeiro uma conexão e retome as outras somente depois que essa atualização for bem-sucedida ou receber uma resposta 4xx.

### Executar um agente em um sandbox

Forneça a um “sandbox” (ambiente isolado) somente o token de acesso, nunca o refresh token. Seu back-end faz a atualização e envia cada novo token de acesso ao sandbox. Ele decide qual cliente um sandbox atende a partir da própria identidade do sandbox, como a identidade do pod, e nunca a partir de um valor que o sandbox envie. Ele envia a um sandbox somente o token desse cliente. O sandbox não deve ser capaz de obter um JWT que corresponda a uma das suas regras de federação ou à autenticação do cliente do seu app. Não forneça a ele nenhum token de identidade montado nem acesso a um servidor de metadados de nuvem.

O Claude Code, o [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) e o Anthropic SDK podem ler o token de um arquivo de credenciais em um perfil de configuração (consulte [Arquivo de configuração de perfil](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#profile-configuration-file)). No sandbox, crie um diretório de configuração com este perfil. Não adicione um `client_id` a ele: com um, o SDK tenta atualizar o token por conta própria.

```json configs/customer.json
{
  "version": "1.0",
  "authentication": {
    "type": "user_oauth"
  }
}
```

Grave o token de acesso como `credentials/customer.json` no mesmo diretório, antes de o agente iniciar e após cada atualização. `expires_at` é o horário de expiração em segundos Unix. Grave um novo arquivo com modo `0600` e renomeie-o sobre o antigo:

```json credentials/customer.json
{
  "type": "oauth_token",
  "access_token": "sk-ant-oat01-...",
  "expires_at": 1793635200
}
```

Defina `ANTHROPIC_CONFIG_DIR` como o diretório de configuração e `ANTHROPIC_PROFILE` como `customer`. Remova a definição de todas as outras credenciais no sandbox, como `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` e a configuração `apiKeyHelper` do Claude Code, pois cada uma delas pode ter precedência sobre o perfil. O agente lê o arquivo novamente nos últimos 2 minutos antes de `expires_at` e após uma resposta 401.

```python
def write_credentials_file(
    config_dir: Path, profile: str, token: str, expires_at: int
) -> None:
    credentials_dir = config_dir / "credentials"
    credentials_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
    body = {"type": "oauth_token", "access_token": token, "expires_at": expires_at}
    # Renomeie um arquivo concluído para o lugar, para que o agente nunca leia meio arquivo.
    # mkstemp define o modo 0600 com o usuário atual como dono, então execute isto como o
    # usuário do agente.
    handle, temporary_path = tempfile.mkstemp(dir=credentials_dir)
    with os.fdopen(handle, "w") as temporary_file:
        json.dump(body, temporary_file)
    os.replace(temporary_path, credentials_dir / f"{profile}.json")
```

### Vincular um cliente novamente

Vincule um cliente novamente nestes casos:

* Uma atualização retornou `invalid_grant`.
* Você perdeu um refresh token, ou um vazou.
* Você perdeu a resposta da Etapa 8 para `billing:attribution offline_access`, ou a Etapa 8 retornou `invalid_grant` para uma conexão desse tipo.
* Um refresh token está próximo da expiração.

Siga estas etapas:

1. Na sua página [User profiles](https://platform.claude.com/user-profiles), verifique se o cliente aparece como **Linked**. Após `invalid_grant`, pergunte primeiro à equipe da sua conta na Anthropic se a organização do cliente está suspensa: depois que uma suspensão termina, o refresh token que você tem volta a funcionar. Se todas as conexões retornarem `invalid_grant` ao mesmo tempo, procure uma causa do seu lado, como um workspace arquivado, antes de desvincular alguém.
2. Se o cliente aparecer como **Linked**, desvincule-o, conforme descrito em [Desvincular um cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer). Desvincular revoga os tokens da conexão. Faça isso quando um administrador da organização do cliente estiver pronto para aprovar, pois o faturamento por meio da conexão é interrompido até que ele aprove.
3. Execute novamente as Etapas 5 a 8 com o perfil de usuário existente do cliente. Armazene o novo ID de conexão e os novos tokens no lugar dos anteriores.

### Desativar a autenticação somente do operador

<Note>
  Durante o beta, pergunte à equipe da sua conta na Anthropic se esta configuração está disponível para sua organização. Enquanto não estiver, você não poderá ativá-la.
</Note>

Para impedir que solicitações que se autenticam apenas como sua conta de serviço operadora faturem clientes, ative **Disable operator-only tokenless authentication** (a configuração `disable_operator_only_auth` do app). Ela fica na aba **Client authentication** do app, abaixo da conta de serviço operadora. Seu app deve ter os escopos `billing:attribution` e `offline_access` e um [workspace para os tokens OAuth dele](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens). Antes de ativá-la, certifique-se de que todos os clientes vinculados aprovaram `billing:attribution offline_access` e de que suas solicitações com os tokens de acesso deles funcionam. Enquanto ela estiver ativada, somente o token de acesso de uma conexão `billing:attribution` pode faturar o cliente dessa conexão. Uma solicitação que se autentica apenas como a conta de serviço e define `bill_to: "user_profile"` é recusada com `403 user_profile_not_billable`. O cliente continua aparecendo como **Linked**, então fique atento a esse erro nos seus logs. A conta de serviço ainda pode gerenciar perfis de usuário e enviar as solicitações pelas quais você paga. Você pode desativar a configuração novamente.

### Inicialização dos trechos de token OAuth

Os exemplos desta seção compartilham a seguinte configuração. Ela define:

* as importações, que incluem o pacote `httpx`
* o client ID do seu app e o tipo de client assertion
* `ConnectionTokens`, que armazena os tokens de uma conexão, seus horários de expiração e sua marca `on_hold`
* `RefreshOnHold`, o erro que `refresh_connection()` gera quando um refresh token não deve ser enviado novamente: ele pode já ter sido usado, ou o endpoint de token respondeu `invalid_grant`. `refresh_connection()` também o gera em todas as chamadas posteriores, até que você remova `on_hold` nos tokens armazenados, por exemplo depois que uma suspensão termina. Quando uma atualização foi bem-sucedida e somente seu cofre de segredos recusou a gravação, o `new_tokens` dele contém os tokens a serem armazenados.
* `client_assertion()`, que lê o JWT do seu provedor de identidade a partir do arquivo indicado por `ANTHROPIC_IDENTITY_TOKEN_FILE`. A claim `aud` do JWT deve ser o audience nas configurações de autenticação do cliente do seu app.
* `load_tokens()` e `save_tokens()`, que você escreve para o seu próprio cofre de segredos

```python
import json
import os
import tempfile
import threading
import time
from collections import defaultdict
from dataclasses import dataclass, field, replace
from pathlib import Path

import httpx

AUTH = "https://auth.claude.com"
# copie de platform.claude.com depois de registrar seu app OAuth.
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# Um refresh que expira aqui perde seus novos tokens, então permita 10 segundos para a
# resposta. Uma conexão que não pode ser feita falha em até 2.
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# Uma segunda requisição deve começar logo após a primeira, ou não começar. A
# página dá 30 segundos, mas mantenha isto abaixo do timeout de leitura de REQUEST_TIMEOUT: uma
# requisição que expirou não deve ser enviada de novo.
SECOND_REQUEST_DEADLINE_SECONDS = 4


@dataclass
class ConnectionTokens:
    refresh_token: str = field(repr=False)
    access_token: str = field(repr=False)
    expires_at: int  # the access token's expiry time, in Unix seconds
    refresh_expires_at: int  # the refresh token's expiry time, in Unix seconds
    # True: o refresh token pode ter sido usado. Não o envie de novo.
    on_hold: bool = False


class RefreshOnHold(Exception):
    """The refresh token might have been used, so a person decides what to do next.

    Don't catch this to try again. If new_tokens is set, the refresh succeeded and
    only the write failed: store those tokens.
    """

    new_tokens: ConnectionTokens | None = None


def client_assertion() -> str:
    """Reads your identity provider's JWT on every call, because its file rotates."""
    return Path(os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]).read_text().strip()


def load_tokens(connection_id: str) -> ConnectionTokens:
    """Reads the connection's newest tokens from your secret store."""
    raise NotImplementedError("Read the tokens from your secret store.")


def save_tokens(connection_id: str, tokens: ConnectionTokens) -> None:
    """Writes the connection's newest tokens to your secret store."""
    raise NotImplementedError("Write the tokens to your secret store.")
```

## Gerenciar suas conexões

### Visualizar clientes no Console

Além da página de apps OAuth, você pode visualizar todos os seus perfis de usuário na página [User profiles](https://platform.claude.com/user-profiles) no Console. Nessa lista e na página de detalhes de cada perfil de usuário, **Your spend** é o seu próprio custo pelas solicitações desse perfil de usuário. É o custo antes de a Anthropic aplicar quaisquer créditos. Essas páginas chamam uma conexão de “link”: um perfil de usuário com uma conexão ativa exibe **Linked**, e um perfil cuja conexão foi encerrada exibe **Unlinked**.

Clique em um perfil de usuário para ver uma visão mais detalhada do uso dele nos últimos 7, 28 ou 90 dias.

### Monitorar o uso de cada cliente

O Claude Console e a [API de Análise de Uso e Custo](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api) informam o uso de cada perfil de usuário. Ambos contabilizam as solicitações pelas quais você paga e as solicitações pelas quais seu cliente paga. Nenhum deles mostra quanto o cliente pagou nem as tarifas do cliente.

No Console, a página [User profiles](https://platform.claude.com/user-profiles) lista **Requests**, **Tokens** e **Your spend** de cada perfil de usuário nos últimos 28 dias. Uma solicitação pela qual seu cliente paga soma aos **Requests** e aos **Tokens** do perfil e não soma nada a **Your spend**.

Chame a API com uma [credencial da Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api#authentication), como um token de acesso OAuth com o escopo `org:admin` ou uma chave de API da Admin API. Não use sua conta de serviço operadora (Etapa 3). A regra de federação dela concede `workspace:developer` por padrão, e não `org:admin`. O escopo `org:admin` abrange toda a Admin API, portanto não o adicione à conta de serviço operadora.

Para gerar relatórios por perfil de usuário por meio da API, chame o [endpoint de uso](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#usage-endpoint) ou o [endpoint de custo](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#cost-endpoint) dela. Para obter uma linha para cada perfil de usuário, agrupe apenas por `user_profile_id` e omita `time_bucket_width`. Somente um perfil de usuário que tenha uso no intervalo de tempo que você solicitar recebe uma linha. Mais uma linha tem `user_profile_id` nulo. Ela contém o uso que não indicou nenhum perfil e o uso medido fora das solicitações, como o tempo de contêiner de execução de código.

No endpoint de custo, uma solicitação pela qual seu cliente paga soma 0 a `amount` e seu preço de tabela a `list_amount`. O campo `amount` é a mesma medida que **Your spend**. A API não tem nenhum campo, filtro ou valor de `group_by[]` que indique quem pagou. Uma linha com `amount` igual a 0 e `list_amount` acima de 0 geralmente significa que o cliente pagou por todas as solicitações dessa linha.

Não use esses números para interromper o uso de um cliente em um valor que você escolher. Nem o Console nem a API informam em tempo real. Os números do Console são atualizados cerca de uma vez por hora, e uma solicitação pode levar algumas horas para aparecer. Para o atraso da API, consulte [Atualização dos dados](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#data-freshness). [Tetos de gastos](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#spend-caps) explica o que os próprios limites do cliente fazem.

### Desvincular um cliente

Para desvincular um cliente no Console, use a lista na [página User profiles](https://platform.claude.com/user-profiles) ou o botão **Unlink** no canto superior direito da página de detalhes de um perfil de usuário.

Para desvincular um cliente a partir do seu back-end, envie o ID de conexão que você armazenou na Etapa 8 ao [endpoint de revogação](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#revocation), com a mesma autenticação do cliente usada na troca do código. Para identificar a conexão pelo perfil de usuário dela, envie `user_profile_id` no lugar de `connection_id`.

<CodeGroup exclude="shell:CLI">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/revoke \
    -H "content-type: application/json" \
    -d @- <<'JSON'
  {
    "connection_id": "ocon_01HV9Z",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
  }
  JSON
  ```

  ```python Python
  def revoke_connection(connection_id: str) -> list[str]:
      response = httpx.post(
          f"{AUTH}/v1/oauth/revoke",
          json={
              "connection_id": connection_id,
              "client_id": CLIENT_ID,
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          },
      )
      response.raise_for_status()
      # IDs das conexões que esta requisição encerrou. A lista fica vazia se a
      # conexão já tiver sido encerrada ou se o ID for desconhecido.
      return response.json()["revoked_connection_ids"]
  ```

  ```typescript TypeScript
  // Nenhum SDK cobre auth.claude.com, então este exemplo o chama diretamente.
  import { readFile } from "node:fs/promises";

  // O ID de conexão que você armazenou na Etapa 8.
  const connectionId = "ocon_01HV9Z";

  // A asserção do cliente: o JWT no arquivo de token de identidade. Leia-o a cada requisição, pois o arquivo é rotacionado.
  // Se a autenticação de cliente do seu app espera um audience diferente do desse JWT, use um segundo arquivo de token.
  const clientAssertion = (
    await readFile(process.env.ANTHROPIC_IDENTITY_TOKEN_FILE!, "utf8")
  ).trim();

  const response = await fetch("https://auth.claude.com/v1/oauth/revoke", {
    method: "POST",
    redirect: "error",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      connection_id: connectionId,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: clientAssertion
    })
  });
  if (!response.ok) {
    throw new Error(`revoke failed: ${response.status}`);
  }

  const { revoked_connection_ids: revokedConnectionIds } = (await response.json()) as {
    revoked_connection_ids: string[];
  };
  console.log(revokedConnectionIds); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```csharp C#
  // Nenhum SDK cobre auth.claude.com, então este exemplo o chama diretamente.
  using System.Net.Http.Json;
  using System.Text.Json;

  // O ID da conexão que você armazenou na Etapa 8.
  var connectionId = "ocon_01HV9Z";

  // A asserção do cliente: o JWT no arquivo de token de identidade. Leia-o a cada requisição, pois o arquivo é rotacionado.
  // Se a autenticação de cliente do seu app espera um audience diferente do que esse JWT tem, use um segundo arquivo de token.
  var tokenFile = Environment.GetEnvironmentVariable("ANTHROPIC_IDENTITY_TOKEN_FILE")!;
  var clientAssertion = (await File.ReadAllTextAsync(tokenFile)).Trim();

  using var http = new HttpClient();
  using var response = await http.PostAsJsonAsync(
      "https://auth.claude.com/v1/oauth/revoke",
      new Dictionary<string, string>
      {
          ["connection_id"] = connectionId,
          ["client_id"] = "YOUR_CLIENT_ID",
          ["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
          ["client_assertion"] = clientAssertion,
      }
  );
  response.EnsureSuccessStatusCode();

  var result = await response.Content.ReadFromJsonAsync<JsonElement>();
  Console.WriteLine(result.GetProperty("revoked_connection_ids")); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```go Go
  // Nenhum SDK cobre auth.claude.com, então este exemplo o chama diretamente.

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"os"
  	"strings"
  )

  func main() {
  	// O ID da conexão que você armazenou na Etapa 8.
  	connectionID := "ocon_01HV9Z"

  	// A asserção do cliente: o JWT no arquivo de token de identidade. Leia-o a cada requisição, pois o arquivo é rotacionado.
  	// Se a autenticação de cliente do seu app espera um audience diferente do que esse JWT tem, use um segundo arquivo de token.
  	token, err := os.ReadFile(os.Getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))
  	if err != nil {
  		panic(err)
  	}

  	body, err := json.Marshal(map[string]string{
  		"connection_id":         connectionID,
  		"client_id":             "YOUR_CLIENT_ID",
  		"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  		"client_assertion":      strings.TrimSpace(string(token)),
  	})
  	if err != nil {
  		panic(err)
  	}

  	response, err := http.Post("https://auth.claude.com/v1/oauth/revoke", "application/json", bytes.NewReader(body))
  	if err != nil {
  		panic(err)
  	}
  	defer response.Body.Close()
  	if response.StatusCode < 200 || response.StatusCode > 299 {
  		panic(fmt.Sprintf("revoke failed: %d", response.StatusCode))
  	}

  	var result struct {
  		RevokedConnectionIDs []string `json:"revoked_connection_ids"`
  	}
  	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
  		panic(err)
  	}
  	fmt.Println(result.RevokedConnectionIDs) // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  }
  ```

  ```java Java
  // Nenhum SDK cobre auth.claude.com, então este exemplo o chama diretamente. O SDK Java inclui o Jackson.
  import com.fasterxml.jackson.databind.ObjectMapper;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;

  void main() throws Exception {
      // O ID da conexão que você armazenou na Etapa 8.
      String connectionId = "ocon_01HV9Z";

      // A asserção do cliente: o JWT no arquivo de token de identidade. Leia-o a cada requisição, pois o arquivo é rotacionado.
      // Se a autenticação de cliente do seu app espera um audience diferente do que esse JWT tem, use um segundo arquivo de token.
      String clientAssertion = Files.readString(
          Path.of(System.getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))).strip();

      var mapper = new ObjectMapper();
      String body = mapper.createObjectNode()
          .put("connection_id", connectionId)
          .put("client_id", "YOUR_CLIENT_ID")
          .put("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
          .put("client_assertion", clientAssertion)
          .toString();

      var request = HttpRequest.newBuilder(URI.create("https://auth.claude.com/v1/oauth/revoke"))
          .header("content-type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(body))
          .build();
      var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() / 100 != 2) {
          throw new IllegalStateException("revoke failed: " + response.statusCode());
      }

      // IDs das conexões que esta requisição encerrou. A lista fica vazia se a conexão já tiver sido encerrada ou o ID for desconhecido.
      IO.println(mapper.readTree(response.body()).get("revoked_connection_ids"));
  }
  ```

  ```php PHP
  // Nenhum SDK cobre auth.claude.com, então este exemplo o chama diretamente.

  // O ID da conexão que você armazenou na Etapa 8.
  $connectionId = 'ocon_01HV9Z';

  // A asserção do cliente: o JWT no arquivo de token de identidade. Leia-o a cada requisição, pois o arquivo é rotacionado.
  // Se a autenticação de cliente do seu app espera um audience diferente do que esse JWT tem, use um segundo arquivo de token.
  $clientAssertion = trim(
      file_get_contents((string) getenv('ANTHROPIC_IDENTITY_TOKEN_FILE'))
          ?: throw new \RuntimeException('the file named by ANTHROPIC_IDENTITY_TOKEN_FILE cannot be read or is empty')
  );

  $body = json_encode([
      'connection_id' => $connectionId,
      'client_id' => 'YOUR_CLIENT_ID',
      'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
      'client_assertion' => $clientAssertion,
  ], JSON_THROW_ON_ERROR);

  $context = stream_context_create(['http' => [
      'method' => 'POST',
      'header' => 'content-type: application/json',
      'content' => $body,
  ]]);
  $response = file_get_contents('https://auth.claude.com/v1/oauth/revoke', context: $context);
  if ($response === false) {
      throw new \RuntimeException('revoke failed');
  }

  /** @var array{revoked_connection_ids: list<string>} $result */
  $result = json_decode($response, associative: true, flags: JSON_THROW_ON_ERROR);
  // IDs das conexões que esta requisição encerrou. A lista fica vazia se a conexão já estava encerrada ou o ID é desconhecido.
  echo implode(', ', $result['revoked_connection_ids']), PHP_EOL;
  ```

  ```ruby Ruby
  # Nenhum SDK cobre auth.claude.com, então este exemplo o chama diretamente.
  require "json"
  require "net/http"

  # O ID da conexão que você armazenou na Etapa 8.
  connection_id = "ocon_01HV9Z"

  # A asserção do cliente: o JWT no arquivo de token de identidade. Leia-o a cada requisição, pois o arquivo é rotacionado.
  # Se a autenticação de cliente do seu app espera um audience diferente do que esse JWT tem, use um segundo arquivo de token.
  client_assertion = File.read(ENV.fetch("ANTHROPIC_IDENTITY_TOKEN_FILE")).strip

  response = Net::HTTP.post(
    URI("https://auth.claude.com/v1/oauth/revoke"),
    {
      connection_id: connection_id,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: client_assertion
    }.to_json,
    "content-type" => "application/json"
  )
  response.value # raises on an error

  # IDs das conexões que esta requisição encerrou. A lista fica vazia se a conexão já estava encerrada ou o ID é desconhecido.
  puts(JSON.parse(response.body).fetch("revoked_connection_ids"))
  ```
</CodeGroup>

`auth.claude.com` responde com HTTP 200 e `revoked_connection_ids`, os IDs das conexões que esta solicitação encerrou. A lista fica vazia se a conexão já tiver sido encerrada, portanto você pode repetir com segurança uma solicitação que envia `connection_id`. Ela também fica vazia se o ID for desconhecido, portanto uma lista vazia não comprova que a conexão existia. Consulte [Revogação](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#revocation) para os outros parâmetros e [Erros do endpoint de revogação](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/oauth-reference#errors-from-the-revocation-endpoint).

Depois que a conexão é encerrada, o perfil de usuário aparece como **Unlinked**, e uma solicitação que define `bill_to: "user_profile"` para este cliente recebe `user_profile_not_billable`. Você ainda pode atender o cliente às suas próprias custas com `bill_to: "self"`. [Após vincular](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#after-connecting) descreve o que seu cliente vê, e [E-mails sobre vínculo e desvínculo](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#emails-to-your-customer) informa qual forma de desvincular envia um e-mail a ele.

### Vincular um cliente a outra organização Claude

Para vincular o perfil de usuário de um cliente a outra organização Claude, desvincule o cliente e, em seguida, vincule-o novamente.

Depois que você desvincula, as solicitações que você fatura a este cliente são recusadas. Isso dura até que um usuário aprove para a outra organização e você troque o código na Etapa 8. Siga estas etapas quando esse usuário estiver pronto para aprovar:

1. Pule esta etapa se o seu cliente já tiver desvinculado seu app na página [Linked platforms](https://platform.claude.com/linked-platforms) dele. Caso contrário, desvincule o cliente, conforme descrito em [Desvincular um cliente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer). O perfil de usuário passa então a aparecer como **Unlinked** na sua página [User profiles](https://platform.claude.com/user-profiles).
2. Execute novamente as [Etapas 5 a 8](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) com o mesmo perfil de usuário. Para a [Etapa 7](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves), o usuário precisa de uma conta que tenha a função Admin ou Faturamento na outra organização. Peça ao usuário que aprove para essa organização.
3. Armazene o novo ID de conexão no lugar do anterior. Se você usa os tokens da conexão, faça o mesmo com os novos tokens.

Até que o cliente seja desvinculado, a página de aprovação permite que um usuário aprove somente para a organização que já está vinculada.

Um teto de gastos pertence a uma organização do cliente e ao seu app, portanto o teto da primeira organização não é transferido. [Tetos de gastos](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#spend-caps) traz as regras.

## Erros esperados

Quando uma solicitação define `bill_to: "user_profile"`, a Anthropic fatura seu cliente ou recusa a solicitação. Ela nunca fatura você silenciosamente no lugar dele. Em `/v1/messages`, o código da lista a seguir está em `error.details.error_code`. Em `/v1/chat/completions`, você recebe o mesmo status HTTP e a mesma mensagem no formato da OpenAI, sem o código:

* `403 permission_error, user_profile_not_billable`: a Anthropic não consegue faturar este cliente por esta solicitação, e a resposta não informa o motivo. Não é possível tentar novamente, exceto nos primeiros 10 segundos após uma nova conexão. Antes de pedir ao cliente que faça o vínculo novamente, consulte [Causas de `user_profile_not_billable`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable): vincular novamente resolve apenas algumas delas. Você ainda pode atender o cliente às suas próprias custas reenviando com `bill_to: "self"`. No Anthropic SDK, trate `user_profile_not_billable` pela [classe de erro](https://platform.claude.com/docs/pt-BR/api/errors#sdk-error-types) do status 403, que é `PermissionDeniedError` (java, php: `PermissionDeniedException`; csharp: `AnthropicForbiddenException`; go: `apierr.StatusCode == http.StatusForbidden`). Ela também corresponde a outros erros 403, portanto verifique também o código de erro.

* `402 billing_error, linked_organization_billing_unavailable`: a Anthropic não consegue faturar a organização do cliente no momento (por exemplo, ela está suspensa, ou o crédito dela se esgota depois que o Claude começou uma resposta). A resposta não informa o motivo. Um cliente que não tem crédito quando a solicitação chega recebe `linked_organization_spend_limit_reached` em vez disso. Não é possível tentar novamente. Diga ao cliente para verificar a conta dele na Claude Platform. Você ainda pode atendê-lo às suas próprias custas reenviando com `bill_to: "self"`.

* `402 billing_error, linked_organization_spend_limit_reached`: a organização do cliente atingiu um limite de gastos que ela mesma definiu. O limite é o [teto de gastos](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#spend-caps) que se aplica ao seu app ou o limite de gastos mensal de toda a organização. 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. A solicitação foi recusada antes que o Claude começasse uma resposta. Não é possível tentar novamente. Você ainda pode atender o cliente às suas próprias custas reenviando com `bill_to: "self"`. Peça ao cliente que verifique estes itens no Claude Console:

  * **O teto de gastos do seu app:** Na página do seu app em [Linked platforms](https://platform.claude.com/linked-platforms), ele pode definir ou aumentar o teto de gastos. Um teto definido ali substitui qualquer teto padrão que ele tenha definido para todas as plataformas vinculadas.
  * **O Limite de gastos mensais da organização:** Em [Limites de gastos](https://platform.claude.com/settings/billing#spend-limits), ele pode aumentá-lo.
  * **O saldo de crédito:** Na página [Faturamento](https://platform.claude.com/settings/billing) dele, ele pode ver o saldo de crédito e comprar créditos. Alguns créditos não podem pagar por essas solicitações: consulte [Quais créditos podem pagar](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#which-credits-can-pay).

* `503 overloaded_error`: a Anthropic não conseguiu confirmar no momento se o cliente pode ser faturado. Tente novamente com backoff e respeite o cabeçalho `retry-after`. A solicitação não foi atendida nem faturada.

* `400 invalid_request_error, user_profile_required`: você definiu `bill_to: "user_profile"` sem o cabeçalho `anthropic-user-profile-id`. Uma solicitação desse tipo precisa do cabeçalho, a menos que use o token de acesso de uma conexão e o cabeçalho seja opcional. Para saber se o cabeçalho é opcional, consulte a nota em [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).

* `400 invalid_request_error`, sem código de erro: o cabeçalho `anthropic-user-profile-id` contém um ID malformado ou que não é um perfil de usuário da sua organização.

* `400 invalid_request_error`, sem código de erro: a solicitação se autenticou com o token de acesso de uma conexão e definiu `bill_to: "self"` ou indicou um perfil de usuário diferente daquele ao qual o token está limitado. 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).

Em `/v1/messages` e `/v1/chat/completions`, o token de acesso de uma conexão não pode enviar uma solicitação pela qual você paga. Para reenviar uma solicitação recusada com `bill_to: "self"`, autentique-se a partir do seu próprio back-end com a própria credencial da sua conta de serviço operadora. [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) lista as recusas do próprio token.

Uma resposta bem-sucedida não informa quem foi faturado, portanto mantenha seu próprio registro de quais solicitações você enviou com `bill_to: "user_profile"`.

### Causas de `user_profile_not_billable`

Verifique estes itens nesta ordem:

* **Sua solicitação.** A solicitação deve se autenticar como a conta de serviço operadora do seu app OAuth (Etapa 3). O [token de acesso de uma conexão](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) também se autentica como essa conta de serviço. Uma solicitação que se autentica de qualquer outra forma é recusada. Exemplos são outra conta de serviço e uma chave de API que não está associada a essa conta de serviço. Se o cabeçalho `anthropic-user-profile-id` indicar um dos seus perfis que não está vinculado, a solicitação é recusada. Se a credencial ou o cabeçalho estiver errado, corrija a solicitação. Uma nova conexão não ajuda.
* **A conexão.** O cliente não fez o vínculo por meio deste app, ou a conexão foi encerrada: um administrador da organização dele ou da sua a encerrou, ou o seu back-end o fez. Uma conexão encerrada aparece como **Unlinked** na sua página [User profiles](https://platform.claude.com/user-profiles). Um perfil vinculado apenas por meio do seu app de teste não está vinculado ao seu app de produção. Pare de faturar esse cliente até que ele faça o vínculo. O token de acesso de uma conexão é limitado a essa conexão, portanto, depois que o cliente fizer o vínculo novamente, use o token de acesso da nova conexão. Se o seu app tiver [desativado a autenticação somente do operador](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), você só poderá faturar um cliente com o token de acesso da conexão dele. Nesse caso, um cliente para o qual você não tem nenhum token funcional de uma conexão `billing:attribution` aparece como **Linked**, mas precisa aprovar novamente, conforme descrito em [Vincular um cliente novamente](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).
* **A organização do cliente.** Ela deve ser de um [cliente elegível](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). Você não consegue verificar isso do seu lado, então pergunte à equipe da sua conta na Anthropic.

Uma nova conexão geralmente funciona de imediato, mas pode levar cerca de 10 segundos após a troca na Etapa 8. Se uma solicitação for recusada com `user_profile_not_billable` nesses 10 segundos, envie-a novamente. Depois disso, esperar ou tentar novamente não altera o resultado. Registre a `error.message` completa e o cabeçalho de resposta `request-id` de cada solicitação recusada. Se um cliente cuja conexão aparece como **Linked** continuar sendo recusado e sua solicitação estiver correta, envie o `request-id` de uma solicitação recusada para a equipe da sua conta na Anthropic, para que a Anthropic possa verificar por que ela foi recusada.

## A visão do seu cliente

### Vincular

Seu usuário aprova em `auth.claude.com` depois que seu app o redireciona na Etapa 6. A [Etapa 7](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves) lista as telas da página de aprovação. Cada tela mostra o nome do seu app e tem um botão **Cancel**. O que o usuário faz em cada tela:

* **Select an organization:** O usuário escolhe qual das organizações Claude dele vincular. A página mostra esta tela somente se o usuário tiver mais de uma organização para escolher.
* **How billing works:** O usuário lê a tela e clica em **Continue**.
* **Set a monthly spend limit:** O usuário insere um limite para seu app em dólares americanos inteiros e clica em **Continue**. O campo de valor começa vazio, portanto a página não escolhe um limite pelo usuário. **Continue without a limit** não salva nenhum novo limite, e um teto ou padrão que o cliente salvou anteriormente continua valendo. O limite que o usuário insere é o teto de gastos descrito em [Tetos de gastos](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#spend-caps). Esta tela é diferente enquanto seu app está em teste: consulte [Enquanto seu app está em teste](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing).
* **A última tela:** Esta tela lista o que seu app poderá fazer, incluindo o limite que o usuário escolheu. O usuário clica em **Link and authorize**.

A página de aprovação usa a conta Claude que estiver conectada no navegador e oferece somente as organizações Claude dessa conta. Essa conta pode não ser a que seu usuário espera, por exemplo, uma conta pessoal em vez de uma de trabalho. Seu app não pode escolher a conta. Os parâmetros do OpenID Connect `prompt=select_account` e `login_hint` não alteram qual conta a página usa.

### Após vincular

Seus clientes gerenciam as conexões deles na página [Linked platforms](https://platform.claude.com/linked-platforms) no Claude Console. Eles podem desvincular seu app a qualquer momento. A Anthropic não notifica você quando isso acontece: você não recebe nenhum evento de webhook nem e-mail.

Depois que um cliente desvincula, as solicitações que você fatura a esse cliente são recusadas com 403 `user_profile_not_billable` (consulte [Causas de `user_profile_not_billable`](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)). O perfil de usuário do cliente aparece como **Unlinked** na sua página [User profiles](https://platform.claude.com/user-profiles) no Console. Para vincular novamente, execute novamente as [Etapas 5 a 8](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) com o perfil de usuário existente do cliente.

### E-mails sobre vínculo e desvínculo

Os e-mails da Anthropic sobre vínculo e desvínculo são enviados aos membros da organização do seu cliente que têm a função Admin ou Faturamento. Cada e-mail contém um link para a página Linked platforms do cliente. O envio de um e-mail pela Anthropic depende do evento:

* **Quando o cliente vincula seu app:** A Anthropic envia um e-mail quando você troca o código na Etapa 8. Ela não envia nada para uma aprovação cujo código você nunca troca. Ela também não envia nada quando um usuário aprova novamente enquanto o cliente ainda está vinculado.
* **Quando o cliente desvincula seu app:** A Anthropic envia um e-mail. Ele não identifica a pessoa que desvinculou seu app.
* **Quando você desvincula o cliente a partir do seu back-end:** A Anthropic envia um e-mail.
* **Quando você desvincula o cliente no Console:** A Anthropic não envia nenhum e-mail.

A Anthropic não garante que um e-mail seja enviado ou entregue. Avise o seu cliente você mesmo quando desvinculá-lo. Não dependa desses e-mails para informar a um cliente que ele está vinculado.

### Tetos de gastos

Seu cliente pode definir um teto de gastos mensal para seu app, em dólares americanos (USD). A página de aprovação chama esse teto de limite de gastos mensal, e o usuário que faz o vínculo pode defini-lo ali (consulte [Vincular](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#connecting)). Ele é separado do **Limite de gastos mensais** da organização, que se aplica à organização inteira. Você não consegue ler o teto de um cliente nem quanto dele o cliente já usou.

Quando os gastos do cliente por meio do seu app atingem o teto, a Claude API recusa as solicitações que você fatura a ele com um 402. Consulte [Erros esperados](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#expected-errors). As recusas duram até 00:00 UTC do primeiro dia do mês seguinte, ou até que o cliente aumente ou remova o teto. Uma alteração no teto pode levar cerca de um minuto para ser aplicada.

Após o vínculo, um membro da organização do cliente com a função Admin ou Faturamento gerencia os tetos na página [Linked platforms](https://platform.claude.com/linked-platforms) no Console:

* **Definir ou alterar um teto:** Ele clica no seu app e, em seguida, em **Set spend cap** ou **Edit spend cap**.
* **Definir um padrão:** Em **Default spend cap**, ele clica em **Set default** ou **Edit**. Cada app vinculado que não tem um teto próprio pode gastar até o valor padrão a cada mês. Os apps não o compartilham.
* **Remover um teto:** Ele clica no seu app, em **Edit spend cap** e, em seguida, em **Remove cap**. Seu app passa então a usar o padrão. Se não houver um padrão, seu app fica sem teto.

O menor teto é $0 USD, que recusa todas as solicitações que você fatura a esse cliente. O Console aceita valores inteiros em dólares, sem um máximo prático. O teto contabiliza os custos de tokens e as taxas de pesquisa na web pelos preços de tabela, antes de qualquer desconto negociado. A fatura do cliente pode diferir do valor que o teto contabiliza.

Um teto pode ser maior que o **Limite de gastos mensais** da organização, que o cliente define em [Limites de gastos](https://platform.claude.com/settings/billing#spend-limits). A Claude API recusa as solicitações que você fatura ao cliente quando qualquer um deles é atingido.

#### Enquanto seu app está em teste

Estes limites se aplicam sempre que alguém vincula seu app ou altera o teto dele enquanto o app está em teste, em análise ou não aprovado:

|                                                     | Em teste, em análise ou não aprovado | Depois que o app está ativo |
| --------------------------------------------------- | ------------------------------------ | --------------------------- |
| Um limite de gastos mensal na página de aprovação   | Obrigatório, $50 USD ou menos        | Opcional                    |
| O campo de valor na página de aprovação             | Começa em $50 USD                    | Começa vazio                |
| **Continue without a limit** na página de aprovação | Não oferecido                        | Oferecido                   |
| Remover o teto no Console                           | Não é possível                       | Possível                    |
| O maior teto que um cliente pode definir            | $50 USD                              | Sem máximo prático          |

Depois que seu app estiver ativo, um teto que um cliente salvou antes disso permanece em vigor. O cliente pode então aumentá-lo ou removê-lo.

### Dar suporte aos seus clientes

Você oferece suporte aos seus clientes em tudo relacionado ao seu app, incluindo o uso do Claude que você cobra deles. A Anthropic fornece aos seus clientes a página de aprovação e a página Linked platforms no Claude Console. Na página Linked platforms, um membro com a função Admin ou Faturamento pode ver quanto seu app custou à organização neste mês. Ele também pode definir um [teto de gastos](https://platform.claude.com/docs/pt-BR/manage-claude/oauth-apps/organization-billing-connections#spend-caps) mensal para seu app e desvinculá-lo. Todas as outras dúvidas sobre seu app devem ser direcionadas a você, então informe aos seus clientes como entrar em contato com você.

## Inicialização dos trechos de código

Os exemplos em Python desta página compartilham a seguinte configuração, que você escreve uma única vez. Ela define:

* as importações
* o client ID e o URI de redirecionamento do seu app
* o valor do cabeçalho beta de faturamento
* um cliente da Claude API que se autentica como sua conta de serviço
* `client_assertion`, que retorna a client assertion que seu back-end envia para `auth.claude.com`

```python
# Os exemplos em Python pressupõem a seguinte inicialização e variáveis
import secrets
from urllib.parse import urlencode

import anthropic
import httpx
from anthropic.lib.credentials import IdentityTokenFile
from anthropic.types import Message
from anthropic.types.beta import BetaMessage
from authlib.oauth2.rfc7636 import create_s256_code_challenge

AUTH = "https://auth.claude.com"
# copie de platform.claude.com depois de registrar seu app OAuth.
CLIENT_ID = "YOUR_CLIENT_ID"
REDIRECT_URI = "https://app.example.com/claude/billing/callback"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
BILLING_BETA = "user-profiles-billing-2026-10-01"

# Cliente da API. O SDK troca o JWT de identidade da sua carga de trabalho por um token
# de acesso e o renova, então você nunca lida com "Bearer <access token>" diretamente.
client = anthropic.Anthropic()

# Asserção de cliente para auth.claude.com: o próprio JWT de identidade, lido novamente
# a cada chamada porque o arquivo é rotacionado. Se as configurações de autenticação
# de cliente do seu app indicarem um público diferente da sua regra de federação, aponte
# para um segundo arquivo de token: IdentityTokenFile("/path/to/other/token").
client_assertion = IdentityTokenFile()
```
