Claude Platform Docs
AdministraçãoClaude Platform OAuth

Linked billing

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.

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 à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, 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 (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 (/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.

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 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 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 e ele estiver ativo, a configuração mostra Any Claude user.

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.

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.

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. Antes de vincular clientes, defina um workspace 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.

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.

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.

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_idPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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. 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). 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.

Navegador
Seu back-end
auth.claude.com
Clicar em “Link your Claude organization”
5
Pushed authorization request com o ID do perfil de usuário e uma asserção de cliente
request_uri
6
Redirecionar para a página de aprovação (o endpoint de autorização)
7
O usuário faz login no Claude, escolhe a organização e aprova
Redirecionar para seu URI de redirecionamento com um código de uso único e o state
Entregar o código e o state
Verificar se o state corresponde
8
Solicitação de token com o código, o code verifier do PKCE e uma asserção de cliente
connection_id
Armazenar o ID de conexão no registro do cliente

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.

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")

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.

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

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

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

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.

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

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.

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.

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"]

A resposta contém o ID da conexão e o “access token” (token de acesso) da conexão, 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 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 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. Consulte Atualizar chamadas ao Claude e Erros esperados 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.

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.
  • 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 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 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 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.
    • 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 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çãoOndeCorreção
O app tem uma conta de serviço operadoraOperator service account na aba Client authentication do appSelecione uma e clique em Save. A Etapa 3 explica como configurar uma.
O workspace do app não está ausente nem arquivadoConfigurar seu appEscolha 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 e Atualizar os tokens.

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

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.

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"}
        },
    )

Se a solicitação for recusada, consulte Erros esperados.

Você paga

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

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,
    )

ou use bill_to: "self":

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"}},
    )

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

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.

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.

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.

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

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, 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, 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.
  • 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 do seu app. Não envie um parâmetro scope.

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

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 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.
  • 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.
  • 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, 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 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). 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.

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:

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.

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

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. 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
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 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 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 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, 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 ou o endpoint de custo 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. Tetos de gastos 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 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, 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.

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"]

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 para os outros parâmetros e Erros do endpoint de revogação.

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 descreve o que seu cliente vê, e E-mails sobre vínculo e desvínculo 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 dele. Caso contrário, desvincule o cliente, conforme descrito em Desvincular um cliente. O perfil de usuário passa então a aparecer como Unlinked na sua página User profiles.
  2. Execute novamente as Etapas 5 a 8 com o mesmo perfil de usuário. Para a Etapa 7, 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 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: 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 do status 403, que é PermissionDeniedError. 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 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, 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, ele pode aumentá-lo.
    • O saldo de crédito: Na página Faturamento 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.
  • 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.
  • 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.

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 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 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. 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, 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.
  • A organização do cliente. Ela deve ser de um cliente elegível. 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 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. Esta tela é diferente enquanto seu app está em teste: consulte Enquanto seu app está em teste.
  • 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 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). O perfil de usuário do cliente aparece como Unlinked na sua página User profiles no Console. Para vincular novamente, execute novamente as Etapas 5 a 8 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). 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. 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 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. 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 aprovadoDepois que o app está ativo
Um limite de gastos mensal na página de aprovaçãoObrigatório, $50 USD ou menosOpcional
O campo de valor na página de aprovaçãoComeça em $50 USDComeça vazio
Continue without a limit na página de aprovaçãoNão oferecidoOferecido
Remover o teto no ConsoleNão é possívelPossível
O maior teto que um cliente pode definir$50 USDSem 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 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
# 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()

Esta página foi útil?