---
title: Linked billing
url: https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections
description: Permite que tus clientes vinculen su organización de Claude Platform a tu app con OAuth y factura el uso de Claude a la organización del cliente.
---

<Warning>
  Claude Platform OAuth es un Beta Service: software previo al lanzamiento proporcionado según tu acuerdo con Anthropic, como los [Términos de Servicio Comerciales](https://www.anthropic.com/legal/commercial-terms), y los [Términos Específicos del Servicio](https://www.anthropic.com/legal/service-specific-terms). Los endpoints, los parámetros y el comportamiento pueden cambiar durante la beta. Es posible que no sea adecuado para uso en producción.
</Warning>

Linked billing permite que tus clientes paguen el uso de Claude en tu app a través de su propia organización de Claude. Un cliente vincula su organización de Claude a tu app una sola vez. La API llama a este vínculo una conexión. Después de que el cliente se haya vinculado, eliges en cada solicitud a la Claude API si paga el cliente o pagas tú. El cliente puede desvincular tu app en cualquier momento. Si una solicitud que marcas para el cliente no se le puede facturar, la Claude API la rechaza en lugar de facturártela a ti.

Esta guía es para desarrolladores cuyos usuarios de la app son principalmente clientes de Claude Platform. Agregas un botón “Link your Claude organization” a tu app. Tu usuario hace clic en él, inicia sesión en Claude y aprueba que tu app facture a su organización de Claude las solicitudes a la Claude API que el cliente te indique realizar. Luego, tu app agrega un campo [`billing_policy`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) a las solicitudes que paga el cliente.

## Clientes y endpoints elegibles

**Clientes elegibles:** A un cliente solo se le puede facturar de esta manera si su organización de Claude Platform le paga directamente a Anthropic por su uso de la API. Cuentan tanto los créditos prepagados como la facturación mediante factura. Las organizaciones facturadas a través de un marketplace en la nube (AWS, Google Cloud o Azure) no pueden facturarse mediante esta integración. Lo mismo ocurre con las organizaciones que solo tienen un plan de suscripción de Claude. Las solicitudes para ellas se rechazan con 403 `user_profile_not_billable`.

Las solicitudes se ejecutan en tu organización, por lo que se aplican tus “rate limits” (límites de velocidad), tu acceso a modelos, tu nivel de servicio, tu retención de datos y tus claves de cifrado. Los acuerdos de datos propios de tu cliente no se aplican a estas solicitudes, incluidos [“zero data retention” (retención cero de datos), o ZDR](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope), un “business associate agreement” (acuerdo de asociado comercial), o BAA, y las “customer-managed encryption keys” (claves de cifrado administradas por el cliente), o CMEK. No vincules clientes que necesiten cobertura de HIPAA, FERPA o CMEK para este uso.

**Endpoints compatibles:** `billing_policy` es compatible con:

* `/v1/messages`
  * Limitación conocida: una solicitud que factura a tu cliente (`bill_to: "user_profile"`) no puede usar [funciones facturables de ejecución de código](https://platform.claude.com/docs/es/about-claude/pricing#code-execution-tool) (la API devuelve un 400), así que envía esas solicitudes con `bill_to: "self"` o sin `billing_policy`.
* `/v1/chat/completions`
* `/v1/messages/count_tokens` acepta el campo `billing_policy` y lo ignora, para que puedas contar los tokens del cuerpo exacto que estás a punto de enviar.

[Message Batches](https://platform.claude.com/docs/es/build-with-claude/batch-processing) (`/v1/messages/batches`) actualmente no admite facturar a tu cliente. Envía las solicitudes en un lote con `bill_to: "self"` o sin `billing_policy`, y se te facturarán como de costumbre. Una solicitud en un lote que establece `bill_to: "user_profile"` se rechaza: su resultado es `errored` con un `invalid_request_error`, no se factura ni a ti ni a tu cliente por ella, y las demás solicitudes del lote se ejecutan como de costumbre.

Para solicitar compatibilidad con otro endpoint, contacta a tu equipo de cuenta de Anthropic.

### Créditos que pueden pagar

No todo el crédito puede pagar una solicitud que una plataforma le factura a un cliente. Lo que puede pagar depende de la organización a la que se factura: el cliente si le facturas a un cliente, o tu organización si una plataforma te factura a ti.

El crédito comprado en la Claude Console para esa organización puede pagar estas solicitudes. Si esa organización tiene facturación mediante factura, se le facturan estas solicitudes.

Algunos créditos promocionales de Anthropic no pueden pagar estas solicitudes. Entre ellos están los créditos mensuales de API que vienen con los planes Claude Max, Ultra y Team. Los créditos de los programas de socios, de capital de riesgo (VC) y para startups de Anthropic no son elegibles para pagar estas solicitudes.

Cuando nada en la cuenta de esa organización puede pagar una solicitud, la Claude API puede rechazarla con un 402. La respuesta no indica si la causa del rechazo fue la falta de crédito o un límite de gasto. Consulta [Errores esperados](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

## Proceso de configuración

Realizas estos tres pasos una sola vez. Registran tu app con Anthropic. Después de ellos, [Qué perfil de usuario vincular](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link) explica una regla que necesitas antes de crear perfiles de usuario.

### Paso 1: Crea la app

Crea la app de OAuth en la Claude Console. Es el registro que identifica tu producto ante Anthropic: vincula tu “redirect URI” (URI de redirección) con un “client ID” (ID de cliente), y su nombre es lo que tu usuario ve en la página de aprobación.

Un miembro de tu organización con el rol Administrador abre la página [Apps de OAuth](https://platform.claude.com/settings/oauth-apps) en la Console y hace clic en **Crear**. Ingresa el nombre de tu app y la URI de redirección (la dirección en tu app a la que regresa el navegador después de la aprobación). En **What the app can do**, selecciona **Bill and link to organizations**.

Se abre la página de la nueva app. Copia el ID de cliente que la Console muestra para la app. Tu app lo envía en el Paso 5 cuando solicita una página de aprobación, en el Paso 6 cuando redirige el navegador y en el Paso 8 cuando intercambia el código, para que Anthropic sepa qué app está haciendo la solicitud. El ID de cliente es público. En la pestaña **Apariencia**, configura el nombre, la página de inicio y la URL del logotipo de tu app.

En la pestaña **Configuración**, **Who can link** muestra **Test users only** para una app nueva, que comienza en modo de prueba. Después de que [publiques tu app](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#publish-your-app) y esté activa, la configuración muestra **Any Claude user**.

<Note>
  Una organización puede registrar varias apps de OAuth, por ejemplo, una para producción y otra para pruebas. Cada app tiene sus propias conexiones: un cliente que vincula tu app de prueba no está vinculado a tu app de producción. Mantén Linked billing en una sola app de producción durante toda la vida de tu integración.
</Note>

### Paso 2: Configura la autenticación del cliente

Configura cómo tu back end demuestra ante `auth.claude.com` que sus solicitudes provienen de tu app. Esto reemplaza a un secreto de cliente: Anthropic no emite secretos de cliente para las apps de OAuth.

En la pestaña **Client authentication** de la app, selecciona tu **Proveedor de identidad** (el emisor que firma los tokens de tu back end). Para agregar uno, haz clic en **Register a new issuer**. Luego configura un **Patrón de asunto**, o condiciones de claims en **Opciones avanzadas de coincidencia**, con las que esos tokens deben coincidir. Después de guardar, la pestaña muestra la audiencia esperada. El claim `aud` de tu aserción de cliente debe ser exactamente ese valor.

<Note>
  Tu app se autentica ante los endpoints de PAR, de token y de revocación con una variación del método `private_key_jwt` (RFC 7523): con cada solicitud, tu back end envía una “client assertion” (aserción de cliente), un JWT que emite tu proveedor de identidad. `auth.claude.com` verifica la firma del token con las claves registradas para ese emisor y lo compara con las condiciones de sujeto o de claims que configuras aquí. Para conocer los claims que debe contener una aserción de cliente, consulta [Claims de la aserción de cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-assertion-claims).
</Note>

### Paso 3: Configura la identidad de tu back end

Tu back end necesita una identidad propia para llamar a la Claude API. Crea dos cosas:

* **Una “service account” (cuenta de servicio).** Es una cuenta no humana en tu organización de Claude. Tu back end se autentica como esta cuenta cuando llama a la Claude API.
* **Una segunda regla de federación.** Al igual que la regla para la autenticación del cliente de la app en el Paso 2, permite que tu back end se autentique con tokens de tu propio proveedor de identidad.

Para configurarlas en la Claude Console, sigue la guía de [Workload Identity Federation](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation).

Luego, en la pestaña **Client authentication** de la app, selecciona esa cuenta de servicio como la cuenta de servicio operadora de la app. Solo esa cuenta de servicio está autorizada para enviar solicitudes de inferencia y atribuir la facturación a los perfiles de usuario vinculados. Una cuenta de servicio puede ser la operadora de una sola app de OAuth.

De forma predeterminada, cualquier solicitud autenticada como esa cuenta de servicio puede facturar a todos los clientes vinculados, configurando el encabezado de perfil de usuario y `bill_to` en la Messages API. Para obtener tokens de autenticación restringidos solo a una conexión específica, consulta [Tokens de OAuth para cada conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection). Antes de vincular clientes, [configura un “workspace” (espacio de trabajo)](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) para tu app. El Paso 8 devuelve un token de este tipo para cada cliente, y requiere que la app especifique un espacio de trabajo predeterminado en tu organización en el que se ejecuta la inferencia. Si quieres “refresh tokens” (tokens de actualización) para cada conexión, activa también **Offline access** para tu app. Luego solicita `offline_access` en el flujo de autorización, en el Paso 5, antes de vincular clientes.

### Qué perfil de usuario vincular

Un “user profile” (perfil de usuario) es un registro en tu propia organización de Claude que representa a uno de tus clientes. Cada solicitud que factura al cliente incluye el ID del perfil, para que Anthropic sepa a qué cliente facturar. Para conocer el resto de lo que hacen los perfiles, consulta [Perfiles de usuario para la atribución a clientes finales](https://platform.claude.com/docs/es/manage-claude/user-profiles).

Decide qué perfil de usuario representa a cada cliente antes de vincular a tu primer cliente. Dentro de una app, las conexiones son de uno a uno:

* La organización de Claude de un cliente solo puede vincularse a uno de tus perfiles de usuario.
* Un perfil de usuario solo puede vincularse a una organización de Claude.

La organización de Claude del cliente es la que el usuario selecciona cuando aprueba tu app. Para saber cómo usan los equipos de un cliente las organizaciones de Claude, pregúntale al cliente. Para aplicar la regla de uno a uno a tus registros de clientes:

* **Varios equipos de un cliente comparten una organización de Claude:** Usa un solo perfil de usuario para todos los equipos.
* **Cada equipo tiene su propia organización de Claude:** Crea un perfil de usuario para cada organización.

Cualquier perfil de usuario activo en tu organización se puede vincular, siempre que se respete la regla de uno a uno. Vincularlo no cambia el perfil, su ID ni su historial de uso. Si vinculas un segundo perfil de usuario a una organización de Claude que ya está vinculada, la aprobación se rechaza: consulta [`user_profile_already_linked`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#user-profile-already-linked).

#### Un perfil de usuario para cada persona

Es posible que ya tengas un perfil de usuario para cada persona que usa tu producto. Varias de esas personas podrían trabajar para un mismo cliente. En ese caso, Anthropic recomienda que crees un perfil de usuario adicional para la organización de Claude del cliente y vincules ese perfil.

El ID de perfil que debes enviar depende de quién paga la solicitud:

* **Solicitudes que facturas al cliente:** Envía el ID del perfil del cliente. Para identificar también a la persona en una solicitud a `/v1/messages`, configura [`metadata.user_id`](https://platform.claude.com/docs/es/api/messages/create) con un identificador para esa persona. Este identificador es opcional y ayuda a Anthropic a detectar el uso indebido por parte de una persona. Usa un valor opaco, no un nombre, una dirección de correo electrónico ni un número de teléfono.
* **Solicitudes que pagas tú:** Puedes seguir enviando el ID del perfil propio de la persona.

## Vincula a cada cliente

Realizas los Pasos 4 a 8 para cada cliente que vincula su organización. Los siguientes fragmentos de código en Python requieren el SDK de Anthropic y algunas importaciones estándar; consulta [Inicialización de los fragmentos de código](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#code-snippet-initialization). Los ejemplos en otros lenguajes y la CLI toman sus credenciales del entorno. Asegúrate de que `ANTHROPIC_API_KEY` no esté configurada, porque tu app necesita autenticarse con Workload Identity Federation.

Agrega un botón “Link your Claude organization” donde tus clientes administran la facturación o las integraciones en tu producto (para el HTML, los colores y el logotipo del botón, consulta [Muestras de marca](https://platform.claude.com/docs/es/manage-claude/oauth-apps/branding-samples#buttons)). Indícales que, para vincularse, deben tener el rol Administrador o Facturación en su organización de Claude.

Para recorrer los pasos tú mismo primero, consulta [Prueba como cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).

<Frame>
  ![Diagrama de secuencia de los Pasos 5 a 8: la solicitud de aprobación, la aprobación del usuario y el intercambio por un ID de conexión](https://platform.claude.com/docs/es/images/oauth-apps-billing-connection-flow.svg)
</Frame>

### Paso 4: Crea un perfil de usuario para el cliente

Crea un perfil de usuario para la organización de Claude de cada cliente y almacena el ID del perfil en el registro del cliente en tu producto.

Si ya tienes un perfil de usuario para la organización de Claude de este cliente, omite este paso y usa el ID de ese perfil. Para decidir qué perfil es, consulta [Qué perfil de usuario vincular](https://platform.claude.com/docs/es/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>

Si tu organización revende acceso a la API, envía también `"access_type": "passthrough"` cuando crees este perfil. Estos ejemplos omiten `access_type`, lo que crea un perfil `application`. Para conocer los dos tipos, consulta [Decide quién obtiene un perfil](https://platform.claude.com/docs/es/manage-claude/user-profiles#decide-who-gets-a-profile).

La respuesta contiene el `id` del perfil, por ejemplo `uprof_01HV9Z`.

<Note>
  Cada solicitud de creación genera un perfil nuevo, incluso con el mismo `reference_id` (tu propio ID para el cliente), así que reutiliza el ID almacenado en lugar de crear un perfil en cada intento de conexión.
</Note>

### Paso 5: Crea una URL de solicitud de autorización enviada

Crea una “pushed authorization request” (solicitud de autorización enviada) que haga referencia al perfil de usuario del cliente del Paso 4. La respuesta te proporciona un `request_uri`. En el siguiente paso, lo usas para redirigir a tu usuario a la página de aprobación.

Antes de enviar la solicitud, tu back end crea dos valores aleatorios y los almacena asociados a la sesión del navegador y al registro del cliente. Usa ambos de nuevo en el Paso 8:

* Un valor `state`, que te permite comprobar que el navegador que regresa a tu app es el que inició esta solicitud.
* Un verificador de código PKCE, un secreto que solo conoce tu back end. La solicitud lleva un hash de él (el desafío de código), y el Paso 8 envía el verificador en sí, para que solo tu back end pueda usar el código que se devuelve.

<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 con HTTP 201, un `request_uri` y un `expires_in` de 600 segundos. El `request_uri` identifica la página de aprobación para esta solicitud. El `scope` debe ser exactamente `billing:attribution` o `billing:attribution offline_access`. Consulta [Alcances para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection) para obtener más detalles. Los ejemplos envían `billing:attribution`. Si tu app no tiene este alcance, agrégalo en **Billing** en la pestaña **Permissions** de la app.

`connection_auth_target` debe ser `platform`: las solicitudes de inferencia se ejecutan en tu propia organización, autenticadas como la cuenta de servicio operadora, pero pueden facturar al cliente.

`user_profile_id` debe ser el ID de un perfil de usuario activo en tu organización. Si la solicitud de autorización enviada falla, `auth.claude.com` devuelve una respuesta de error de OAuth a tu back end. En ese caso, no redirijas el navegador.

### Paso 6: Envía a tu usuario a la página de aprobación de Claude

Primero, muéstrale a tu usuario qué cuenta de tu producto está vinculando e indícale que compruebe la cuenta de Claude que muestra la página de aprobación. La página muestra qué cuenta de Claude tiene la sesión iniciada y permite que el usuario cambie a otra. La página de aprobación ofrece solo las organizaciones de la cuenta de Claude que tiene la sesión iniciada en el navegador, por lo que la cuenta equivocada puede vincular la organización equivocada. La organización que vincula el usuario es la que paga.

<Note>
  La persona que aprueba debe ser administradora de la organización de Claude del cliente: un miembro con el rol Administrador o Facturación.
</Note>

Luego, redirige a tu usuario al endpoint de autorización, que muestra una página de aprobación. Incluye solo tu `client_id` y el `request_uri` del Paso 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
```

### Paso 7: El usuario aprueba

Tu app no hace nada en este paso. El usuario realiza estos pasos en `auth.claude.com`:

1. El usuario inicia sesión en Claude, a menos que el navegador ya tenga la sesión iniciada.

2. La página de aprobación muestra las siguientes pantallas, cada una con el nombre de tu app. Para saber qué hace el usuario en cada pantalla, consulta [Vinculación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connecting).

   1. **Select an organization**, solo si el usuario puede elegir entre varias organizaciones.
   2. **How billing works**.
   3. **Set a monthly spend limit**.
   4. Una última pantalla con un botón **Link and authorize**.

3. Cuando el usuario hace clic en **Link and authorize**, `auth.claude.com` devuelve el navegador a tu app. La página de aprobación no muestra ninguna pantalla de confirmación.

Si el usuario cancela o no puede aprobar, no se crea ninguna conexión: consulta [Si la vinculación no se completa](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

<Note>
  La conexión pertenece a toda la organización de Claude, no al usuario que la aprobó. Si ese usuario abandona la organización, la conexión permanece activa. Cualquier administrador de la organización del cliente o de la tuya puede finalizar la conexión en cualquier momento, y tu back end también puede hacerlo.
</Note>

### Paso 8: Gestiona el callback y guarda la conexión

Después de la aprobación, `auth.claude.com` devuelve el navegador a tu URI de redirección con un código de un solo uso y tu valor `state`. Esta solicitud a tu URI de redirección se denomina “callback” (devolución de llamada). Tu back end intercambia el código por un ID de conexión y lo almacena en el registro del cliente. Esto completa la conexión. El callback puede llevar un parámetro `error` y ningún código. En ese caso, no se creó ninguna conexión: consulta [Si la vinculación no se completa](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

Comprueba que el `state` coincida con el valor que almacenaste en el Paso 5 y luego intercambia el código de inmediato desde tu back end, junto con el verificador de código PKCE. El código es de un solo uso y vence después de 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 los tokens de la conexión, guarda tokens["access_token"], su hora de
      # expiración (de tokens["expires_in"]) y, con offline_access,
      # tokens["refresh_token"] como secretos aquí: el código no se puede volver a intercambiar.
      # "ocon_..."; guárdalo en el registro del cliente
      return tokens["connection_id"]
  ```
</CodeGroup>

La respuesta contiene el ID de conexión y [el token de acceso de la conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection), que puede autenticar y facturar al cliente que aprobó. Si el cliente aprobó `offline_access`, la respuesta también contiene un token de actualización. Almacena `connection_id` y los tokens ahora: el intercambio devuelve los tokens solo una vez. [Almacena los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) describe la respuesta.

Los ejemplos de esta página que llaman a la Claude API se autentican como la cuenta de servicio del Paso 3, no con un token de esta respuesta. [Llama a Claude con el token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token) explica cómo usar el token en su lugar.

La respuesta no identifica qué organización de Claude vinculó el usuario.

Una conexión completada no garantiza que Anthropic pueda facturar al cliente. Por ejemplo, es posible que la organización del cliente no sea uno de los [clientes elegibles](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). Consulta [Actualiza las llamadas a Claude](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) y [Errores esperados](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#expected-errors) para ver cómo la Claude API lo comprueba. Debido a esa comprobación, redacta tu mensaje de éxito como “vinculado” en lugar de “facturación activa”.

Si el intercambio se rechaza con `unauthorized_client`, consulta [El intercambio del código devuelve `unauthorized_client`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client).

<Note>
  Un usuario puede aprobar de nuevo para un perfil de usuario que ya está vinculado. El resultado depende de los alcances:

  * Aprobado de nuevo para el mismo perfil de usuario y los mismos alcances: la conexión se mantiene y la respuesta del token devuelve el mismo `connection_id` y un nuevo token de acceso. La excepción es una conexión con `billing:attribution offline_access`: el intercambio del código devuelve `invalid_grant`, la conexión se mantiene como estaba y [Vuelve a vincular a un cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again) explica qué hacer.
  * Aprobado de nuevo para el mismo perfil de usuario con otros alcances, por ejemplo `billing:attribution offline_access` después de `billing:attribution`: tu intercambio del nuevo código crea una nueva conexión con un nuevo `connection_id`, que reemplaza a la anterior. Los tokens de una conexión `billing:attribution` anterior se revocan. Almacena el nuevo `connection_id` en lugar del anterior. Si el intercambio falla con una respuesta 5xx, ejecuta de nuevo los Pasos 5 a 8. [Alcances para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection) explica cuándo necesitas esto.
  * Después de que se revoca una conexión, puedes volver a vincular el mismo perfil de usuario.
</Note>

### Prueba como cliente

Para comprobar que la vinculación funciona, vincula una organización propia. Primero necesitas lo siguiente:

* Una segunda organización de Claude propia que actúe como cliente. No puedes vincular tu app a la organización que es su propietaria. La página de aprobación no ofrece esa organización. La segunda organización debe ser uno de los [clientes elegibles](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints).
* Una persona con el rol Administrador o Facturación en esa organización para aprobar el vínculo.
* Hasta que tu app esté activa, esa persona debe estar en la lista **Test users** de tu app. La lista se encuentra en la pestaña **Configuración** de la app, en **Who can link**. Agrega a la persona mediante la dirección de correo electrónico de su cuenta de Claude y haz clic en **Save changes**. [Mientras tu app está en pruebas](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing) indica el tope de gasto que se aplica. Quitar a alguien de la lista finaliza los vínculos que esa persona aprobó.

Luego, ejecuta los Pasos 4 a 8 y haz que esa persona apruebe en el Paso 7. Cuando se crea el vínculo, el perfil de usuario muestra **Linked** en tu página [User profiles](https://platform.claude.com/user-profiles) de la Console.

### Si la vinculación no se completa

Cuando el usuario no termina la aprobación, o `auth.claude.com` la rechaza, no se crea ninguna conexión. Estas entradas cubren los resultados específicos de Linked billing. Para todos los demás errores, consulta [Errores](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#errors) en la Referencia de OAuth.

#### Tu URI de redirección recibe `error=access_denied`

La solicitud también lleva tu valor `state`. Tu URI de redirección recibe este error en casos como estos:

1. El usuario hace clic en **Cancel** en cualquier pantalla de aprobación.

2. La página de aprobación no tiene ninguna organización que ofrecerle al usuario, y el usuario hace clic en el botón que regresa a tu app. Por ejemplo:

   * El usuario no tiene el rol Administrador o Facturación en ninguna organización de Claude Platform.
   * La única organización del usuario es la que es propietaria de tu app. Consulta [Prueba como cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).
   * El perfil de usuario ya está vinculado a otra organización de Claude, y el usuario no tiene el rol Administrador o Facturación en esa organización.
   * Hasta que tu app esté activa, el usuario no está en su lista **Test users**.

En cada caso de esta lista, el `error_description` dice `the user declined the request`, por lo que no puedes usarlo para distinguirlos.

Hay una causa más en la configuración de tu app. Si tu app está activa y **Who can link** muestra solo tu organización, nadie fuera de tu organización puede vincular la app. Selecciona **Any Claude user** y haz clic en **Save changes**.

Indícale al usuario que la vinculación no se completó, y no supongas que la rechazó. Pídele que compruebe con qué cuenta de Claude inició sesión y su rol en la organización que quiere vincular. Un `request_uri` no se puede volver a usar después de que el usuario cancela o regresa, así que, para permitir que el usuario lo intente de nuevo, comienza de nuevo desde el Paso 5.

#### Tu app recibe `user_profile_already_linked`

La organización de Claude del cliente ya está vinculada a tu app a través de otro de tus perfiles de usuario. `auth.claude.com` le pide al usuario que se comunique contigo. Si el usuario regresa a tu app, tu URI de redirección recibe `error=user_profile_already_linked` y tu valor `state`. El endpoint de token también puede devolver este error cuando intercambias el código en el Paso 8. Eso sucede, por ejemplo, cuando la organización se vinculó mientras tanto a través de otro perfil de usuario.

Anthropic no te indica qué organización de Claude vincula un cliente, por lo que no puedes saberlo de antemano. La solicitud de autorización enviada del Paso 5 se completa, y `auth.claude.com` rechaza la conexión solo cuando el usuario aprueba.

El error no indica el perfil de usuario que tiene la conexión. Lo más probable es que sea otro perfil vinculado de este cliente. Anthropic no muestra a qué organización está vinculado un perfil, así que confírmalo con el cliente antes de actuar. Si ese perfil tiene la conexión, haz una de las siguientes acciones:

* En las solicitudes que facturas a este cliente, envía el ID de ese perfil de usuario.
* Finaliza esa conexión, como se describe en [Desvincular a un cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer), y luego ejecuta de nuevo los Pasos 5 a 8 con el perfil de usuario que se rechazó.

Si ninguno de los perfiles de este cliente está vinculado, es posible que el usuario haya seleccionado una organización que pertenece a otro de tus clientes. Comienza de nuevo desde el Paso 5 y pide al usuario que compruebe qué organización selecciona.

#### Tu URI de redirección no recibe nada

Tu app no puede detectar estos dos casos:

* El usuario cierra la página de aprobación.
* El `request_uri` venció o ya se usó. En ese caso, la página de aprobación muestra un error y no devuelve el navegador a tu app.

Si el usuario regresa a tu producto sin un callback, comienza de nuevo desde el Paso 5. Un `request_uri` que no se usó vence 10 minutos después de que lo creaste.

#### El intercambio del código devuelve `unauthorized_client`

Tu app no está configurada para esta solicitud. Para un problema con el espacio de trabajo, el `error_description` indica la causa. Para una cuenta de servicio operadora faltante, solo dice `the client is not registered for this grant`. El rechazo no consume el código, así que puedes intercambiar el mismo código de nuevo hasta que venza. Primero, comprueba lo siguiente en la Claude Console:

| Comprobación                                               | Dónde                                                                                                                                                     | Solución                                                                                                                    |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| La app tiene una cuenta de servicio operadora              | **Operator service account** en la pestaña **Client authentication** de la app                                                                            | Selecciona una y haz clic en **Save**. El Paso 3 explica cómo configurar una.                                               |
| El espacio de trabajo de la app no falta ni está archivado | [Configura tu app](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) | Elige un espacio de trabajo. Mientras la app no tenga ninguno, el intercambio también se rechaza con `unauthorized_client`. |

Una cuenta de servicio guardada puede tardar uno o dos minutos en llegar a `auth.claude.com`, así que, si el intercambio se rechaza de nuevo, espera ese tiempo y vuelve a intentarlo. Si para entonces el código ya venció, pide al usuario que apruebe de nuevo (Pasos 5 a 8). Para conocer las causas que `error_description` indica para los tokens de una conexión, consulta [Almacena los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) y [Actualiza los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).

En cualquier otro caso, contacta a tu equipo de cuenta de Anthropic. Haz lo mismo si la Console indica que la cuenta de servicio ya no existe.

### Publica tu app

Hasta que tu app esté publicada, solo las personas de su lista **Test users** pueden vincularla, así que tus clientes no pueden hacerlo. Para publicar la app, haz clic en **Publish app** en la página de la app en la Claude Console. Se abre un cuadro de diálogo.

* Si tu organización tiene facturación mediante factura, la app se publica en cuanto confirmas en ese cuadro de diálogo.
* De lo contrario, primero demuestras en ese cuadro de diálogo que controlas el dominio de la app y luego Anthropic revisa la app.

**La prueba de dominio:** El dominio es el dominio de la página de inicio de tu app. Cada URI de redirección debe estar en ese dominio o en un subdominio de él, excepto una en `localhost`, `127.0.0.1` o `[::1]`. La prueba es un registro DNS TXT. Los cambios de DNS pueden tardar hasta 48 horas, así que comienza antes de que necesites que los clientes se vinculen. Si tu organización ya demostró un dominio que abarca la página de inicio y esas URI de redirección, el cuadro de diálogo omite la prueba. Un dominio demostrado abarca sus subdominios.

Confirmas en el último paso del cuadro de diálogo. Si ese paso muestra una casilla para aceptar los Linked Billing Terms, selecciónala. Luego, haz clic en **Publish app** en el cuadro de diálogo.

**La revisión:** Durante la revisión, el estado de la app en la Console indica **In review**. La app se publica cuando Anthropic la aprueba. Si Anthropic no la aprueba, el estado indica **Not approved**, y no puedes volver a publicar la app por tu cuenta. Para consultar sobre la decisión, contacta al soporte.

A menos que tu organización tenga facturación mediante factura, un cambio en el nombre, el logotipo, la página de inicio o las URI de redirección de una app publicada devuelve la app a revisión. Los clientes que ya están vinculados siguen vinculados y conservan el tope que guardaron. Hasta que Anthropic apruebe el cambio, solo las personas de la lista **Test users** pueden vincular la app.

## Actualiza las llamadas a Claude

Envía el encabezado `anthropic-user-profile-id` en cada llamada a `/v1/messages` y `/v1/chat/completions` para un cliente vinculado. En una solicitud que facturas al cliente, el valor del encabezado es el ID del perfil de usuario que tiene la conexión de ese cliente. Las llamadas que configuran `billing_policy` también deben enviar el encabezado beta `user-profiles-billing-2026-10-01`.

Cada solicitud para un cliente vinculado se factura al cliente o a ti, y eliges a quién en cada solicitud. Los siguientes ejemplos muestran ambos casos.

[Tokens de OAuth para cada conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) describe otra forma de autenticar las solicitudes de un cliente: un token de acceso que solo puede facturar a ese cliente. En `/v1/messages` y `/v1/chat/completions`, una solicitud con un token así no se te puede facturar a ti. Se factura a ese cliente, incluso sin `billing_policy` ni el encabezado `anthropic-user-profile-id`, en los casos en que estos sean opcionales: consulta la nota en [Llama a Claude con el token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token). Si indica otro perfil de usuario o establece `bill_to: "self"`, se rechaza. Nunca uses uno para una solicitud que pagas tú.

### Tu cliente paga

Agrega `billing_policy` con `bill_to: "user_profile"` al cuerpo de la solicitud y envía el encabezado beta de facturación y el encabezado del ID de perfil.

<Warning>
  Comprueba que el encabezado indique el perfil del cliente para el que es la solicitud. De forma predeterminada, la credencial propia de tu cuenta de servicio operadora puede facturar a todos los clientes vinculados a través de esta app. Si una solicitud con esa credencial indica un perfil diferente vinculado a través de esta app, Anthropic factura a la organización de ese perfil, y ningún error te lo indica. El [token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) solo puede facturar a su propio cliente.
</Warning>

Establece `bill_to: "user_profile"` solo en las solicitudes que el cliente te indique realizar: el uso de Claude que el cliente y sus usuarios generan en tu producto. No le factures a un cliente tu propio uso, como pruebas, evaluaciones o trabajo para otros clientes. La Claude API no puede verificar esto por ti, así que es tu responsabilidad.

<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 aún no está en los tipos del 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>

Si la solicitud se rechaza, consulta [Errores esperados](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

### Tú pagas

Para pagar tú, omite por completo `billing_policy` (en cuyo caso el encabezado beta de facturación es 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>

o usa `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 aún no está en los tipos del 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 de OAuth para cada conexión

Tu back end llama a la Claude API como la cuenta de servicio operadora de tu app (Paso 3). De forma predeterminada, cualquier solicitud autenticada como esa cuenta de servicio puede facturar a todos los clientes vinculados, pasando un encabezado de ID de perfil de usuario e incluyendo `bill_to` en las solicitudes a la Messages API. Este comportamiento predeterminado se denomina “operator-only tokenless authentication” (autenticación sin token solo para el operador).

Para gestionar implementaciones de un solo inquilino de tu producto, o entornos de sandbox controlados por el cliente, puedes obtener tokens de acceso y de actualización de OAuth vinculados a una conexión en lugar de usar la autenticación sin token solo para el operador.

Para cada conexión, el intercambio del código en el Paso 8 devuelve el token de acceso propio de esa conexión. El token se autentica como tu cuenta de servicio operadora, pero solo puede facturar al cliente de esa conexión. Vence en un plazo de 1 hora.

Para autenticar cada conexión por separado:

* **Usa el acceso sin conexión.** Activa [**Offline access**](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) para tu app y solicita `offline_access` en el Paso 5. Así, cada conexión también obtiene un token de actualización, que tu back end usa para solicitar nuevos tokens de acceso. Sin él, el cliente debe aprobar de nuevo para darte un nuevo token de acceso: ejecuta de nuevo los Pasos 5 a 8 con el mismo `scope`.
* **Configura un espacio de trabajo predeterminado.** [Elige un espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) en tu organización en el que se ejecuten las solicitudes con estos tokens.
* **Opcionalmente, desactiva la autenticación sin token solo para el operador.** De forma predeterminada, aún puedes facturar a un cliente vinculado como tu cuenta de servicio operadora (pasando un encabezado de perfil de usuario y `bill_to`), incluso después de que venza el token de acceso del cliente. Después de [desactivar la autenticación solo del operador](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), cada solicitud que factura a un cliente debe autenticarse con el token de acceso de ese cliente.
* **Usa `billing:attribution`.** Solo este alcance le da a una conexión sus propios tokens. Aún puedes facturar a un cliente vinculado como tu cuenta de servicio operadora, como con `org:billing_attribution`, que está obsoleto. Consulta [Alcances para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection).

### Configura tu app

Las solicitudes con el token de acceso de una conexión se ejecutan en un espacio de trabajo de tu organización. Toda app necesita uno, incluso si no usas estos tokens: mientras tu app no tenga un espacio de trabajo, el intercambio del código en el Paso 8 se rechaza con `unauthorized_client`.

Un miembro de tu organización con el rol Administrador abre la pestaña **Client authentication** de la app en la Console. Debajo de la cuenta de servicio operadora, busca **Default workspace for platform auth mode OAuth tokens** (la configuración `connection_token_workspace_id` de la app) y haz clic en **Choose workspace**. Selecciona un espacio de trabajo del que la cuenta de servicio operadora (Paso 3) sea miembro. El espacio de trabajo no debe estar archivado.

Para obtener tokens de actualización, activa **Offline access** en la pestaña **Permissions** de la app. Un cambio en los alcances de la app tarda unos minutos en llegar a `auth.claude.com`.

<Note>
  Archivar el espacio de trabajo predeterminado revoca todos los tokens que se ejecutan en él, y no se puede deshacer. Para pasar a otro espacio de trabajo, configura el nuevo y espera unos minutos. Una actualización antes de que el cambio llegue a `auth.claude.com` puede devolver tokens que aún se ejecutan en el espacio de trabajo anterior. Luego, actualiza todas las conexiones que tengan un token de actualización y solo entonces archiva el espacio de trabajo anterior. Si archivas un espacio de trabajo primero, deja de actualizar sus conexiones antes de configurar otro: una actualización posterior finaliza la conexión.

  No cambies ni archives la cuenta de servicio operadora de la app mientras haya un cliente vinculado. Después de cambiarla o archivarla, `auth.claude.com` rechaza todas las actualizaciones, y los tokens que tienes pronto dejan de facturar a los clientes. Cada cliente cuyos tokens uses debe entonces vincularse de nuevo: para obtener ayuda, [contacta al soporte](https://support.claude.com/en/articles/9015913-how-to-get-support).
</Note>

### Alcances para una conexión de facturación

En el Paso 5, envía `scope` como `billing:attribution`. Para obtener también un “refresh token” (token de actualización), envía `billing:attribution offline_access`.

Para cambiar los alcances de un cliente que ya está vinculado, por ejemplo para agregar `offline_access`, ejecuta de nuevo los Pasos 5 a 8 con el perfil de usuario existente del cliente y el nuevo `scope`. No necesitas desvincularlo primero. El intercambio del código devuelve un nuevo `connection_id`, y la nueva conexión reemplaza a la anterior. Consulta la nota del Paso 8.

Una app puede tener `billing:attribution` y el obsoleto `org:billing_attribution` al mismo tiempo. Agregas `billing:attribution` en **Billing**, en la pestaña **Permissions** de la app. Si quitas `org:billing_attribution` allí, no puedes volver a agregarlo. Una conexión que un cliente aprobó con `org:billing_attribution` sigue facturando a través de tu cuenta de servicio operadora hasta que la conexión finaliza o [desactivas la autenticación solo del operador](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication).

### Almacena los tokens

El intercambio del código devuelve los tokens solo una vez, así que almacénalos en el Paso 8. La respuesta contiene `access_token`, `expires_in` (como máximo 1 hora, en segundos) y `connection_id`. Si el cliente aprobó `offline_access`, también contiene `refresh_token` y `refresh_token_expires_in`. Un token de actualización dura como máximo 1 año, y una actualización no extiende ese plazo. Después de eso, [vuelve a vincular al cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

Almacena los tokens y sus tiempos de vencimiento en un almacén de secretos que solo pueda leer el servicio que realiza las actualizaciones.

Si el intercambio se rechaza con `unauthorized_client`, `error_description` indica la causa, como un espacio de trabajo faltante o archivado. El código no se consume: corrige la causa y envía el mismo código de nuevo antes de que venza.

### Llama a Claude con el token de acceso de una conexión

<Note>
  Durante la beta, pregúntale a tu equipo de cuenta de Anthropic si las solicitudes a la Claude API con el token de acceso de una conexión están habilitadas para tu organización. Mientras no lo estén, todas esas solicitudes fallan, sin importar lo que envíen. Pregunta también si el encabezado `anthropic-user-profile-id` y `billing_policy` son opcionales. Mientras no lo sean, envía cada solicitud a `/v1/messages` y `/v1/chat/completions` que use el token de acceso de una conexión como se muestra en [Tu cliente paga](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#your-customer-pays), con el encabezado, `bill_to: "user_profile"` y el encabezado beta de facturación.
</Note>

Envía el token de acceso de la conexión como token de portador en el encabezado `Authorization`, en lugar de la credencial propia de tu cuenta de servicio operadora. No envíes un encabezado `x-api-key`. En el SDK de Anthropic, pasa el token como `auth_token` (typescript, php: `authToken`; java: `.authToken()`; csharp: `AuthToken`; go: `option.WithAuthToken()`), o configura la variable de entorno `ANTHROPIC_AUTH_TOKEN`.

En `/v1/messages` y `/v1/chat/completions`, la solicitud se factura al cliente de esa conexión. El encabezado `anthropic-user-profile-id` y `billing_policy` son opcionales. Necesitas el encabezado beta de facturación solo con `billing_policy`.

En estos dos endpoints, no puedes pagar una solicitud con este token. Usa el token solo en estos dos endpoints, en `/v1/messages/count_tokens` y en los endpoints de Models. Envía todas las demás solicitudes, y todas las solicitudes que pagas tú, como tu cuenta de servicio operadora, desde tu propio back end. Eso incluye una solicitud que use [funciones facturables de ejecución de código](https://platform.claude.com/docs/es/about-claude/pricing#code-execution-tool), que no pueden facturarse a un cliente.

La Claude API rechaza estas solicitudes:

* `400 invalid_request_error`, sin código de error: la solicitud indicó otro perfil de usuario o estableció `bill_to: "self"`.
* `403 permission_error`, sin código de error: la solicitud se envió a un endpoint de [Message Batches](https://platform.claude.com/docs/es/build-with-claude/batch-processing).
* `401 authentication_error`: el token venció, una actualización lo reemplazó o su conexión finalizó. Después de que una conexión finaliza, la respuesta también puede ser `403 user_profile_not_billable`.

### Actualiza los tokens

Para renovar el token de acceso de una conexión, envía su token de actualización al endpoint de token, `https://auth.claude.com/v1/oauth/token`, con la [autenticación del cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-authentication) de tu app. No envíes un 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
      # Un 503 en el formato de la Claude API con un encabezado retry-after es un rechazo
      # que no usa el refresh token. Cualquier otra respuesta 5xx cuenta 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 un solo proceso. Si el servicio tiene réplicas, usa un lock
      # que todas compartan.
      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"
          # Pon la conexión en espera antes de que el refresh token salga de este proceso.
          # Si el proceso se detiene antes de guardar los tokens nuevos, la espera se mantiene.
          save_tokens(connection_id, replace(tokens, on_hold=True))
          issued_at = int(time.time())
          started = time.monotonic()
          # httpx no reintenta por sí solo. No agregues reintentos: un reintento tardío termina la
          # conexión.
          try:
              response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
              lost = is_lost(response)
          except (httpx.ConnectError, httpx.ConnectTimeout):
              # No se estableció conexión, así que el refresh token nunca salió de este proceso.
              save_tokens(connection_id, tokens)
              raise
          except httpx.TransportError:
              lost = True
          if lost:
              # Es posible que la primera solicitud haya usado el refresh token. Una segunda solicitud
              # solo es segura dentro del límite anterior, así que envía una de inmediato o ninguna
              # en absoluto.
              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:
                  # Tras cualquier respuesta que no sean tokens nuevos, no puedes saber si la
                  # primera solicitud tuvo efecto, y una solicitud posterior no es segura.
                  raise hold_error(connection_id, "The second refresh failed.")
          if error_body(response).get("error") == "invalid_grant":
              # Expirado, ya usado o la conexión terminó. Enviarlo de nuevo
              # puede terminar la conexión.
              raise hold_error(connection_id, "The refresh returned invalid_grant.")
          if response.status_code != 200:
              # Un rechazo que conserva el refresh token, así que quita la 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"],
          )
          # Si la escritura falla, vuelve a intentar la escritura. No vuelvas a actualizar.
          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)
          # Los tokens nuevos solo existen en este proceso, y el refresh token almacenado
          # ya se consumió. El registro almacenado sigue en espera. El error lleva los nuevos
          # tokens, para que quien llama pueda guardarlos cuando el almacén de secretos vuelva.
          error = hold_error(
              connection_id,
              "The refresh succeeded, but the new tokens could not be saved.",
          )
          error.new_tokens = tokens
          raise error
  ```
</CodeGroup>

La respuesta contiene un nuevo `access_token` y un nuevo `refresh_token`. El token de actualización que enviaste queda reemplazado: no lo envíes de nuevo, excepto como lo indica la lista de fallos que aparece más abajo. El token de acceso anterior deja de funcionar en unos pocos minutos. [Inicialización de los fragmentos de tokens de OAuth](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#oauth-token-snippet-initialization) define las funciones que llama el ejemplo.

* Almacena el nuevo token de actualización antes de usar el nuevo token de acceso.
* Actualiza los tokens de cada conexión desde un solo servicio, una actualización a la vez. Si el servicio tiene réplicas, usa un “lock” (bloqueo) que compartan todas ellas. Un token de actualización usado que llega de nuevo más de 30 segundos después de su primer uso finaliza la conexión. Se revocan todos los tokens, el cliente se muestra como **Unlinked** y ninguna credencial puede facturarle hasta que se vuelva a vincular.
* Desactiva los reintentos automáticos para la solicitud de actualización, en tu cliente HTTP y en cualquier proxy.

Si la primera solicitud con un token de actualización falla:

* La solicitud no pudo conectarse: el token de actualización no se envió. Vuelve a intentarlo más tarde.

* Una conexión interrumpida, o cualquier respuesta 5xx distinta del `503` de esta lista: no puedes saber si la solicitud surtió efecto, así que envía el mismo token de actualización una vez más.

  1. Envíalo de inmediato, y solo si han pasado menos de 30 segundos desde que enviaste la primera solicitud.
  2. Si devuelve nuevos tokens, almacénalos y usa solo esos. Si la primera solicitud sí surtió efecto, sus tokens, que nunca te llegaron, se revocan.
  3. Si devuelve cualquier otra cosa o no obtiene respuesta, o si ya pasaron los 30 segundos, no vuelvas a enviar ese token de actualización. Deja de actualizar esa conexión y [vuelve a vincular al cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* Un tiempo de espera agotado: es posible que la solicitud aún se esté ejecutando. No vuelvas a enviar ese token de actualización. Deja de actualizar esa conexión y [vuelve a vincular al cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* `429`, o `503` con un encabezado `retry-after` y `"type": "error"` en el nivel superior de su cuerpo: no se revoca nada. Espera al menos el tiempo que indica el encabezado y envía de nuevo el mismo token de actualización.

* `unauthorized_client` o `invalid_client`: no se revoca nada. `error_description` indica la causa, como un espacio de trabajo faltante, `offline_access` que ya no está registrado para tu app o una aserción de cliente fallida. Corrígela y envía de nuevo el mismo token de actualización.

* `invalid_scope`: la solicitud envió un parámetro `scope`, o `billing:attribution` ya no está registrado para tu app. No se revoca nada. Corrige la causa y envía de nuevo el mismo token de actualización.

* `invalid_grant`: el token de actualización venció o ya se usó, la conexión finalizó o la organización del cliente está suspendida. Deja de actualizar esa conexión y sigue [Vuelve a vincular a un cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again), que comienza con una comprobación de suspensión.

Si una conexión interrumpida, una respuesta 5xx o un tiempo de espera agotado te llevó a dejar de actualizar una conexión, pausa también las actualizaciones de tus otras conexiones. Cuando las reanudes, actualiza primero una conexión y reanuda las demás solo después de que esa actualización tenga éxito o reciba una respuesta 4xx.

### Ejecuta un agente en un sandbox

Dale a un “sandbox” (entorno aislado) solo el token de acceso, nunca el token de actualización. Tu back end realiza las actualizaciones y envía cada nuevo token de acceso al sandbox. Decide a qué cliente atiende un sandbox a partir de la identidad propia del sandbox, como su identidad de pod, y nunca a partir de un valor que envíe el sandbox. Envía a un sandbox solo el token de ese cliente. El sandbox no debe poder obtener un JWT que coincida con alguna de tus reglas de federación o con la autenticación del cliente de tu app. No le des ningún token de identidad montado ni acceso a un servidor de metadatos de la nube.

Claude Code, el [Claude Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview) y el SDK de Anthropic pueden leer el token desde un archivo de credenciales en un perfil de configuración (consulta [Archivo de configuración del perfil](https://platform.claude.com/docs/es/manage-claude/wif-reference#profile-configuration-file)). En el sandbox, crea un directorio de configuración con este perfil. No le agregues un `client_id`: con uno, el SDK intenta actualizar el token por sí mismo.

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

Escribe el token de acceso como `credentials/customer.json` en el mismo directorio, antes de que se inicie el agente y después de cada actualización. `expires_at` es el tiempo de vencimiento en segundos Unix. Escribe un archivo nuevo con el modo `0600` y renómbralo sobre el anterior:

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

Configura `ANTHROPIC_CONFIG_DIR` con el directorio de configuración y `ANTHROPIC_PROFILE` con `customer`. Elimina todas las demás credenciales del sandbox, como `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` y la configuración `apiKeyHelper` de Claude Code, porque cada una puede tener prioridad sobre el perfil. El agente vuelve a leer el archivo en los últimos 2 minutos antes de `expires_at` y después de una respuesta 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}
    # Renombra un archivo terminado a su lugar, para que el agente nunca lea medio archivo.
    # mkstemp establece el modo 0600 con el usuario actual como dueño, así que ejecuta esto como el
    # usuario del 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")
```

### Vuelve a vincular a un cliente

Vuelve a vincular a un cliente en estos casos:

* Una actualización devolvió `invalid_grant`.
* Perdiste un token de actualización, o se filtró uno.
* Perdiste la respuesta del Paso 8 para `billing:attribution offline_access`, o el Paso 8 devolvió `invalid_grant` para una conexión de ese tipo.
* Un token de actualización está cerca de su vencimiento.

Sigue estos pasos:

1. En tu página [User profiles](https://platform.claude.com/user-profiles), comprueba si el cliente se muestra como **Linked**. Después de `invalid_grant`, pregúntale primero a tu equipo de cuenta de Anthropic si la organización del cliente está suspendida: después de que termina una suspensión, el token de actualización que tienes vuelve a funcionar. Si todas las conexiones devuelven `invalid_grant` al mismo tiempo, busca una causa de tu lado, como un espacio de trabajo archivado, antes de desvincular a alguien.
2. Si el cliente se muestra como **Linked**, desvincúlalo, como se describe en [Desvincular a un cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer). Desvincular revoca los tokens de la conexión. Hazlo cuando un administrador de la organización del cliente esté listo para aprobar, porque la facturación a través de la conexión se detiene hasta que lo haga.
3. Ejecuta de nuevo los Pasos 5 a 8 con el perfil de usuario existente del cliente. Almacena el nuevo ID de conexión y los nuevos tokens en lugar de los anteriores.

### Desactiva la autenticación solo del operador

<Note>
  Durante la beta, pregúntale a tu equipo de cuenta de Anthropic si esta configuración está disponible para tu organización. Mientras no lo esté, no puedes activarla.
</Note>

Para impedir que las solicitudes que se autentican solo como tu cuenta de servicio operadora facturen a los clientes, activa **Disable operator-only tokenless authentication** (la configuración `disable_operator_only_auth` de la app). Se encuentra en la pestaña **Client authentication** de la app, debajo de la cuenta de servicio operadora. Tu app debe tener los alcances `billing:attribution` y `offline_access` y un [espacio de trabajo para sus tokens de OAuth](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens). Antes de activarla, asegúrate de que cada cliente vinculado haya aprobado `billing:attribution offline_access` y de que tus solicitudes con sus tokens de acceso funcionen. Mientras está activada, solo el token de acceso de una conexión `billing:attribution` puede facturar al cliente de esa conexión. Una solicitud que se autentica solo como la cuenta de servicio y establece `bill_to: "user_profile"` se rechaza con `403 user_profile_not_billable`. El cliente se sigue mostrando como **Linked**, así que vigila este error en tus registros. La cuenta de servicio aún puede administrar perfiles de usuario y enviar las solicitudes que pagas tú. Puedes volver a desactivar la configuración.

### Inicialización de los fragmentos de tokens de OAuth

Los ejemplos de esta sección comparten la siguiente configuración. Define:

* las importaciones, que incluyen el paquete `httpx`
* el ID de cliente de tu app y el tipo de aserción de cliente
* `ConnectionTokens`, que contiene los tokens de una conexión, sus tiempos de vencimiento y su marca `on_hold`
* `RefreshOnHold`, el error que `refresh_connection()` genera cuando un token de actualización no debe enviarse de nuevo: es posible que ya se haya usado, o el endpoint de token respondió `invalid_grant`. `refresh_connection()` también lo genera en cada llamada posterior, hasta que borres `on_hold` en los tokens almacenados, por ejemplo después de que termine una suspensión. Cuando una actualización tuvo éxito y solo tu almacén de secretos rechazó la escritura, su `new_tokens` contiene los tokens que debes almacenar.
* `client_assertion()`, que lee el JWT de tu proveedor de identidad desde el archivo que indica `ANTHROPIC_IDENTITY_TOKEN_FILE`. El claim `aud` del JWT debe ser la audiencia de la configuración de autenticación del cliente de tu app.
* `load_tokens()` y `save_tokens()`, que escribes para tu propio almacén de secretos

```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"
# cópialos de platform.claude.com después de registrar tu app de OAuth.
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# Una actualización que agota el tiempo aquí pierde sus tokens nuevos, así que da 10 segundos para la
# respuesta. Una conexión que no se puede establecer falla en menos de 2.
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# Una segunda solicitud debe iniciarse así de pronto tras la primera, o nunca. La
# página da 30 segundos, pero mantén esto por debajo del tiempo de lectura de REQUEST_TIMEOUT: una
# solicitud que agotó el tiempo no debe enviarse de nuevo.
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: es posible que el refresh token se haya usado. No lo envíes de nuevo.
    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.")
```

## Administra tus conexiones

### Ver clientes en la Console

Además de la página de apps de OAuth, puedes ver todos tus perfiles de usuario en la página [User profiles](https://platform.claude.com/user-profiles) de la Console. En esa lista y en la página de detalles de cada perfil de usuario, **Your spend** es tu propio costo por las solicitudes de ese perfil de usuario. Es el costo antes de que Anthropic aplique cualquier crédito. Estas páginas llaman “link” (vínculo) a una conexión: un perfil de usuario con una conexión activa muestra **Linked**, y uno cuya conexión ha finalizado muestra **Unlinked**.

Haz clic en un perfil de usuario para ver su uso con más detalle durante los últimos 7, 28 o 90 días.

### Supervisar el uso de cada cliente

Tanto la Claude Console como la [API de análisis de uso y costos](https://platform.claude.com/docs/es/manage-claude/usage-cost-analytics-api) informan el uso de cada perfil de usuario. Ambas cuentan las solicitudes que pagas tú y las solicitudes que paga tu cliente. Ninguna muestra lo que pagó el cliente ni las tarifas del cliente.

En la Console, la página [User profiles](https://platform.claude.com/user-profiles) enumera **Requests**, **Tokens** y **Your spend** para cada perfil de usuario durante los últimos 28 días. Una solicitud que paga tu cliente se suma a **Requests** y **Tokens** del perfil y no suma nada a **Your spend**.

Llama a la API con una [credencial de la Admin API](https://platform.claude.com/docs/es/manage-claude/admin-api#authentication), como un token de acceso de OAuth con el alcance `org:admin` o una clave de la Admin API. No uses tu cuenta de servicio operadora (Paso 3). Su regla de federación otorga `workspace:developer` de forma predeterminada, no `org:admin`. El alcance `org:admin` cubre toda la Admin API, así que no se lo agregues a la cuenta de servicio operadora.

Para generar informes por perfil de usuario a través de la API, llama a su [endpoint de uso](https://platform.claude.com/docs/es/manage-claude/usage-cost-analytics-api#usage-endpoint) o a su [endpoint de costos](https://platform.claude.com/docs/es/manage-claude/usage-cost-analytics-api#cost-endpoint). Para obtener una fila por cada perfil de usuario, agrupa solo por `user_profile_id` y omite `time_bucket_width`. Solo obtiene una fila un perfil de usuario que tenga uso en el rango de tiempo que solicitas. Hay una fila más con un `user_profile_id` nulo. Contiene el uso que no indicó ningún perfil y el uso que se mide fuera de las solicitudes, como el tiempo de contenedor de ejecución de código.

En el endpoint de costos, una solicitud que paga tu cliente suma 0 a `amount` y su precio de lista a `list_amount`. El campo `amount` es la misma medida que **Your spend**. La API no tiene ningún campo, filtro ni valor de `group_by[]` que indique quién pagó. Una fila con un `amount` de 0 y un `list_amount` mayor que 0 suele significar que el cliente pagó todas las solicitudes de esa fila.

No uses estas cifras para detener el uso de un cliente en un monto que tú elijas. Ni la Console ni la API informan en tiempo real. Las cifras de la Console se actualizan aproximadamente una vez por hora, y una solicitud puede tardar algunas horas en aparecer. Para conocer el retraso de la API, consulta [Actualización de los datos](https://platform.claude.com/docs/es/manage-claude/usage-cost-analytics-api#data-freshness). [Topes de gasto](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#spend-caps) indica lo que hacen los límites propios del cliente.

### Desvincular a un cliente

Para desvincular a un cliente en la Console, usa la lista de la [página User profiles](https://platform.claude.com/user-profiles) o el botón **Unlink** en la parte superior derecha de la página de detalles de un perfil de usuario.

Para desvincular a un cliente desde tu back end, envía el ID de conexión que almacenaste en el Paso 8 al [endpoint de revocación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#revocation), con la misma autenticación del cliente que en el intercambio del código. Para indicar la conexión por su perfil de usuario en su lugar, envía `user_profile_id` en 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 de las conexiones que finalizó esta solicitud. La lista está vacía si la
      # conexión ya había finalizado o el ID es desconocido.
      return response.json()["revoked_connection_ids"]
  ```

  ```typescript TypeScript
  // Ningún SDK cubre auth.claude.com, así que este ejemplo lo llama directamente.
  import { readFile } from "node:fs/promises";

  // El ID de conexión que guardaste en el Paso 8.
  const connectionId = "ocon_01HV9Z";

  // La aserción del cliente: el JWT del archivo de token de identidad. Léelo en cada solicitud, ya que el archivo rota.
  // Si la autenticación de cliente de tu app espera una audiencia distinta a la de ese JWT, usa un segundo archivo 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#
  // Ningún SDK cubre auth.claude.com, así que este ejemplo lo llama directamente.
  using System.Net.Http.Json;
  using System.Text.Json;

  // El ID de conexión que guardaste en el Paso 8.
  var connectionId = "ocon_01HV9Z";

  // La aserción del cliente: el JWT del archivo de token de identidad. Léelo en cada solicitud, ya que el archivo rota.
  // Si la autenticación de cliente de tu app espera una audiencia distinta a la de ese JWT, usa un segundo archivo 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
  // Ningún SDK cubre auth.claude.com, así que este ejemplo lo llama directamente.

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

  func main() {
  	// El ID de conexión que guardaste en el Paso 8.
  	connectionID := "ocon_01HV9Z"

  	// La aserción del cliente: el JWT del archivo de token de identidad. Léelo en cada solicitud, ya que el archivo rota.
  	// Si la autenticación de cliente de tu app espera una audiencia distinta a la de ese JWT, usa un segundo archivo 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
  // Ningún SDK cubre auth.claude.com, así que este ejemplo lo llama directamente. El SDK de Java incluye 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 {
      // El ID de conexión que guardaste en el Paso 8.
      String connectionId = "ocon_01HV9Z";

      // La aserción del cliente: el JWT del archivo de token de identidad. Léelo en cada solicitud, ya que el archivo rota.
      // Si la autenticación de cliente de tu app espera una audiencia distinta a la de ese JWT, usa un segundo archivo 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 de las conexiones que finalizó esta solicitud. La lista está vacía si la conexión ya había finalizado o el ID es desconocido.
      IO.println(mapper.readTree(response.body()).get("revoked_connection_ids"));
  }
  ```

  ```php PHP
  // Ningún SDK cubre auth.claude.com, así que este ejemplo lo llama directamente.

  // El ID de conexión que guardaste en el Paso 8.
  $connectionId = 'ocon_01HV9Z';

  // La aserción del cliente: el JWT del archivo de token de identidad. Léelo en cada solicitud, porque el archivo rota.
  // Si la autenticación de cliente de tu app espera una audiencia distinta a la de ese JWT, usa un segundo archivo 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 de las conexiones que finalizó esta solicitud. La lista está vacía si la conexión ya había finalizado o el ID es desconocido.
  echo implode(', ', $result['revoked_connection_ids']), PHP_EOL;
  ```

  ```ruby Ruby
  # Ningún SDK cubre auth.claude.com, así que este ejemplo lo llama directamente.
  require "json"
  require "net/http"

  # El ID de conexión que guardaste en el paso 8.
  connection_id = "ocon_01HV9Z"

  # La aserción del cliente: el JWT del archivo de token de identidad. Léelo en cada solicitud, porque el archivo rota.
  # Si la autenticación de cliente de tu app espera una audiencia distinta a la de ese JWT, usa un segundo archivo 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 de las conexiones que esta solicitud finalizó. La lista está vacía si la conexión ya había finalizado o el ID es desconocido.
  puts(JSON.parse(response.body).fetch("revoked_connection_ids"))
  ```
</CodeGroup>

`auth.claude.com` responde con HTTP 200 y `revoked_connection_ids`, los IDs de las conexiones que finalizó esta solicitud. La lista está vacía si la conexión ya había finalizado, así que puedes repetir con seguridad una solicitud que envíe `connection_id`. También está vacía si el ID es desconocido, por lo que una lista vacía no demuestra que la conexión existiera. Consulta [Revocación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#revocation) para conocer los demás parámetros y [Errores del endpoint de revocación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#errors-from-the-revocation-endpoint).

Después de que la conexión finaliza, el perfil de usuario se muestra como **Unlinked**, y una solicitud que configura `bill_to: "user_profile"` para este cliente recibe `user_profile_not_billable`. Aún puedes atender al cliente a tu propio costo con `bill_to: "self"`. [Después de vincularse](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#after-connecting) describe lo que ve tu cliente, y [Correos electrónicos sobre la vinculación y la desvinculación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#emails-to-your-customer) indica qué forma de desvincular le envía un correo electrónico.

### Vincular a un cliente a otra organización de Claude

Para vincular el perfil de usuario de un cliente a otra organización de Claude, desvincula al cliente y luego vincúlalo de nuevo.

Después de desvincularlo, las solicitudes que le facturas a este cliente se rechazan. Esto dura hasta que un usuario aprueba para la otra organización y tú intercambias el código en el Paso 8. Sigue estos pasos cuando ese usuario esté listo para aprobar:

1. Omite este paso si tu cliente ya desvinculó tu app en su página [Linked platforms](https://platform.claude.com/linked-platforms). De lo contrario, desvincula al cliente, como se describe en [Desvincular a un cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer). El perfil de usuario se muestra entonces como **Unlinked** en tu página [User profiles](https://platform.claude.com/user-profiles).
2. Ejecuta de nuevo [los Pasos 5 a 8](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) con el mismo perfil de usuario. Para el [Paso 7](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves), el usuario necesita una cuenta que tenga el rol Administrador o Facturación en la otra organización. Pide al usuario que apruebe para esa organización.
3. Almacena el nuevo ID de conexión en lugar del anterior. Si usas los tokens de la conexión, haz lo mismo con los nuevos tokens.

Hasta que se desvincule al cliente, la página de aprobación solo permite que un usuario apruebe para la organización que ya está vinculada.

Un tope de gasto pertenece a una organización del cliente y a tu app, por lo que el tope de la primera organización no se traslada. [Topes de gasto](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#spend-caps) explica las reglas.

## Errores esperados

Cuando una solicitud configura `bill_to: "user_profile"`, Anthropic factura a tu cliente o rechaza la solicitud. Nunca te factura a ti en su lugar de forma silenciosa. En `/v1/messages`, el código de la siguiente lista está en `error.details.error_code`. En `/v1/chat/completions` obtienes el mismo estado HTTP y el mismo mensaje en formato de OpenAI, sin el código:

* `403 permission_error, user_profile_not_billable`: Anthropic no puede facturar a este cliente por esta solicitud, y la respuesta no indica el motivo. No se puede reintentar, excepto en los primeros 10 segundos después de una nueva conexión. Antes de pedirle al cliente que se vuelva a vincular, consulta [Causas de `user_profile_not_billable`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable): volver a vincularse solo resuelve algunas de ellas. Aún puedes atender al cliente a tu propio costo reenviando la solicitud con `bill_to: "self"`. En el SDK de Anthropic, gestiona `user_profile_not_billable` mediante la [clase de error](https://platform.claude.com/docs/es/api/errors#sdk-error-types) del estado 403, que es `PermissionDeniedError` (java, php: `PermissionDeniedException`; csharp: `AnthropicForbiddenException`; go: `apierr.StatusCode == http.StatusForbidden`). Esto también coincide con otros errores 403, así que comprueba también el código de error.

* `402 billing_error, linked_organization_billing_unavailable`: Anthropic no puede facturar actualmente a la organización del cliente (por ejemplo, está suspendida, o su crédito se agota después de que Claude haya comenzado una respuesta). La respuesta no indica el motivo. Un cliente que no tiene crédito cuando llega la solicitud recibe `linked_organization_spend_limit_reached` en su lugar. No se puede reintentar. Indícale al cliente que revise su cuenta de Claude Platform. Aún puedes atenderlo a tu propio costo reenviando la solicitud con `bill_to: "self"`.

* `402 billing_error, linked_organization_spend_limit_reached`: la organización del cliente ha alcanzado un límite de gasto que estableció. El límite es el [tope de gasto](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#spend-caps) que se aplica a tu app o el límite de gasto mensual de toda la organización. La Claude API envía el mismo código cuando la organización no tiene crédito que pueda pagar la solicitud. La respuesta no indica cuál. La solicitud se rechazó antes de que Claude comenzara a responder. No se puede reintentar. Aún puedes atender al cliente a tu propio costo reenviando la solicitud con `bill_to: "self"`. Pídele al cliente que revise lo siguiente en la Claude Console:

  * **El tope de gasto de tu app:** En la página de tu app en [Linked platforms](https://platform.claude.com/linked-platforms), puede establecer o aumentar el tope de gasto. Un tope establecido allí reemplaza cualquier tope predeterminado que haya establecido para todas las plataformas vinculadas.
  * **El Límite de gasto mensual de la organización:** En [Límites de gasto](https://platform.claude.com/settings/billing#spend-limits), puede aumentarlo.
  * **El saldo de crédito:** En su página [Facturación](https://platform.claude.com/settings/billing), puede ver su saldo de crédito y comprar créditos. Algunos créditos no pueden pagar estas solicitudes: consulta [Créditos que pueden pagar](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#which-credits-can-pay).

* `503 overloaded_error`: Anthropic no pudo confirmar en este momento si se puede facturar al cliente. Reintenta con “backoff” (espera progresiva) y respeta el encabezado `retry-after`. La solicitud no se atendió ni se facturó.

* `400 invalid_request_error, user_profile_required`: configuraste `bill_to: "user_profile"` sin el encabezado `anthropic-user-profile-id`. Una solicitud así necesita el encabezado, a menos que use el token de acceso de una conexión y el encabezado sea opcional. Para saber si el encabezado es opcional, consulta la nota en [Llama a Claude con el token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

* `400 invalid_request_error`, sin código de error: el encabezado `anthropic-user-profile-id` contiene un ID que tiene un formato incorrecto o que no es un perfil de usuario de tu organización.

* `400 invalid_request_error`, sin código de error: la solicitud se autenticó con el token de acceso de una conexión y estableció `bill_to: "self"` o indicó un perfil de usuario distinto de aquel al que está limitado el token. Consulta [Llama a Claude con el token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

En `/v1/messages` y `/v1/chat/completions`, el token de acceso de una conexión no puede enviar una solicitud que pagas tú. Para reenviar una solicitud rechazada con `bill_to: "self"`, autentícate desde tu propio back end con la credencial propia de tu cuenta de servicio operadora. [Llama a Claude con el token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token) enumera los rechazos del propio token.

Una respuesta exitosa no indica a quién se facturó, así que lleva tu propio registro de qué solicitudes enviaste con `bill_to: "user_profile"`.

### Causas de `user_profile_not_billable`

Comprueba estas causas en orden:

* **Tu solicitud.** La solicitud debe autenticarse como la cuenta de servicio operadora de tu app de OAuth (Paso 3). El [token de acceso de una conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) también se autentica como esa cuenta de servicio. Se rechaza una solicitud que se autentique de cualquier otra forma. Algunos ejemplos son una cuenta de servicio diferente y una clave de API que no está asociada a esa cuenta de servicio. Si el encabezado `anthropic-user-profile-id` indica uno de tus perfiles que no está vinculado, la solicitud se rechaza. Si la credencial o el encabezado son incorrectos, corrige la solicitud. Una nueva conexión no ayuda.
* **La conexión.** El cliente no se ha vinculado a través de esta app, o la conexión finalizó: un administrador de su organización o de la tuya la finalizó, o lo hizo tu back end. Una conexión finalizada se muestra como **Unlinked** en tu página [User profiles](https://platform.claude.com/user-profiles). Un perfil vinculado solo a través de tu app de prueba no está vinculado a tu app de producción. Deja de facturar a ese cliente hasta que se vincule. El token de acceso de una conexión está limitado a esa conexión, así que después de que el cliente se vuelva a vincular, usa el token de acceso de la nueva conexión. Si tu app [desactivó la autenticación solo del operador](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), solo puedes facturar a un cliente con el token de acceso de su conexión. En ese caso, un cliente para el que no tienes ningún token funcional de una conexión `billing:attribution` se muestra como **Linked**, pero debe aprobar de nuevo, como se describe en [Vuelve a vincular a un cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).
* **La organización del cliente.** Debe ser un [cliente elegible](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). No puedes comprobarlo desde tu lado, así que pregúntale a tu equipo de cuenta de Anthropic.

Una nueva conexión suele funcionar de inmediato, pero puede tardar unos 10 segundos después del intercambio del Paso 8. Si una solicitud se rechaza con `user_profile_not_billable` en esos 10 segundos, envíala de nuevo. Después de eso, esperar o reintentar no cambia el resultado. Registra el `error.message` completo y el encabezado de respuesta `request-id` de cada solicitud rechazada. Si un cliente cuya conexión se muestra como **Linked** sigue siendo rechazado y tu solicitud es correcta, envía el `request-id` de una solicitud rechazada a tu equipo de cuenta de Anthropic, para que Anthropic pueda averiguar por qué se rechazó.

## La vista de tu cliente

### Vinculación

Tu usuario aprueba en `auth.claude.com` después de que tu app lo redirige en el Paso 6. El [Paso 7](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves) enumera las pantallas de la página de aprobación. Cada pantalla muestra el nombre de tu app y tiene un botón **Cancel**. Lo que hace el usuario en cada pantalla:

* **Select an organization:** El usuario elige cuál de sus organizaciones de Claude vincular. La página muestra esta pantalla solo si el usuario puede elegir entre varias organizaciones.
* **How billing works:** El usuario lee la pantalla y hace clic en **Continue**.
* **Set a monthly spend limit:** El usuario ingresa un límite para tu app en dólares estadounidenses enteros y hace clic en **Continue**. El campo del monto comienza vacío, por lo que la página no elige un límite por el usuario. **Continue without a limit** no guarda ningún límite nuevo, y un tope o un valor predeterminado que el cliente haya guardado antes sigue aplicándose. El límite que ingresa el usuario es el tope de gasto que se describe en [Topes de gasto](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#spend-caps). Esta pantalla es diferente mientras tu app está en pruebas: consulta [Mientras tu app está en pruebas](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing).
* **La última pantalla:** Esta pantalla enumera lo que tu app podrá hacer, incluido el límite que eligió el usuario. El usuario hace clic en **Link and authorize**.

La página de aprobación usa la cuenta de Claude que tenga la sesión iniciada en el navegador, y ofrece solo las organizaciones de Claude de esa cuenta. Es posible que esa cuenta no sea la que tu usuario espera, por ejemplo, una cuenta personal en lugar de una del trabajo. Tu app no puede elegir la cuenta. Los parámetros de OpenID Connect `prompt=select_account` y `login_hint` no cambian qué cuenta usa la página.

### Después de vincularse

Tus clientes administran sus conexiones en la página [Linked platforms](https://platform.claude.com/linked-platforms) de la Claude Console. Pueden desvincular tu app en cualquier momento. Anthropic no te notifica cuando lo hacen: no recibes ningún evento de webhook ni ningún correo electrónico.

Después de que un cliente se desvincula, las solicitudes que le facturas a ese cliente se rechazan con 403 `user_profile_not_billable` (consulta [Causas de `user_profile_not_billable`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)). El perfil de usuario del cliente aparece como **Unlinked** en tu página [User profiles](https://platform.claude.com/user-profiles) de la Console. Para volver a vincularse, ejecuta de nuevo [los Pasos 5 a 8](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) con el perfil de usuario existente del cliente.

### Correos electrónicos sobre la vinculación y la desvinculación

Los correos electrónicos de Anthropic sobre la vinculación y la desvinculación se envían a los miembros de la organización de tu cliente que tienen el rol Administrador o Facturación. Cada correo electrónico incluye un enlace a la página Linked platforms del cliente. Que Anthropic envíe un correo electrónico depende del evento:

* **Cuando el cliente vincula tu app:** Anthropic envía un correo electrónico cuando intercambias el código en el Paso 8. No envía nada por una aprobación cuyo código nunca intercambias. Tampoco envía nada cuando un usuario aprueba de nuevo mientras el cliente sigue vinculado.
* **Cuando el cliente desvincula tu app:** Anthropic envía un correo electrónico. El correo electrónico no indica el nombre de la persona que desvinculó tu app.
* **Cuando desvinculas al cliente desde tu back end:** Anthropic envía un correo electrónico.
* **Cuando desvinculas al cliente en la Console:** Anthropic no envía ningún correo electrónico.

Anthropic no garantiza que se envíe o se entregue un correo electrónico. Avísale tú mismo a tu cliente cuando lo desvincules. No dependas de estos correos electrónicos para informarle a un cliente que está vinculado.

### Topes de gasto

Tu cliente puede establecer un “spend cap” (tope de gasto) mensual para tu app, en dólares estadounidenses (USD). La página de aprobación llama a este tope un límite de gasto mensual, y el usuario que vincula puede establecerlo allí (consulta [Vinculación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#connecting)). Es independiente del **Límite de gasto mensual** de la organización, que se aplica a toda la organización. No puedes leer el tope de un cliente ni cuánto ha usado de él.

Cuando el gasto del cliente a través de tu app alcanza el tope, la Claude API rechaza las solicitudes que le facturas con un 402. Consulta [Errores esperados](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#expected-errors). Los rechazos duran hasta las 00:00 UTC del primer día del mes siguiente, o hasta que el cliente aumente o elimine el tope. Un cambio en el tope puede tardar aproximadamente un minuto en aplicarse.

Después de vincularse, un miembro de la organización del cliente con el rol Administrador o Facturación administra los topes en la página [Linked platforms](https://platform.claude.com/linked-platforms) de la Console:

* **Establecer o cambiar un tope:** Hace clic en tu app y luego en **Set spend cap** o **Edit spend cap**.
* **Establecer un valor predeterminado:** En **Default spend cap**, hace clic en **Set default** o **Edit**. Cada app vinculada que no tiene un tope propio puede gastar hasta el valor predeterminado cada mes. Las apps no lo comparten.
* **Eliminar un tope:** Hace clic en tu app, en **Edit spend cap** y luego en **Remove cap**. Tu app pasa entonces a usar el valor predeterminado. Si no hay un valor predeterminado, tu app no tiene tope.

El tope más pequeño es de $0 USD, que rechaza todas las solicitudes que le facturas a ese cliente. La Console acepta dólares enteros y no tiene un máximo práctico. El tope cuenta los costos de tokens y las tarifas de búsqueda web a precios de lista, antes de cualquier descuento negociado. La factura del cliente puede diferir del monto que cuenta el tope.

Un tope puede ser mayor que el **Límite de gasto mensual** de la organización, que el cliente establece en [Límites de gasto](https://platform.claude.com/settings/billing#spend-limits). La Claude API rechaza las solicitudes que le facturas al cliente cuando se alcanza cualquiera de los dos.

#### Mientras tu app está en pruebas

Estos límites se aplican cada vez que alguien vincula tu app o cambia su tope mientras la app está en pruebas, en revisión o no aprobada:

|                                                         | En pruebas, en revisión o no aprobada | Después de que la app está publicada |
| ------------------------------------------------------- | ------------------------------------- | ------------------------------------ |
| Un límite de gasto mensual en la página de aprobación   | Obligatorio, de $50 USD o menos       | Opcional                             |
| El campo del monto en la página de aprobación           | Comienza en $50 USD                   | Comienza vacío                       |
| **Continue without a limit** en la página de aprobación | No se ofrece                          | Se ofrece                            |
| Eliminar el tope en la Console                          | No es posible                         | Es posible                           |
| El tope más grande que puede establecer un cliente      | $50 USD                               | Sin máximo práctico                  |

Una vez que tu app está publicada, un tope que un cliente haya guardado antes se mantiene. Luego, el cliente puede aumentarlo o eliminarlo.

### Brindar soporte a tus clientes

Tú brindas soporte a tus clientes en todo lo relacionado con tu app, incluido el uso de Claude que les facturas. Anthropic ofrece a tus clientes la página de aprobación y la página Linked platforms en la Claude Console. En la página Linked platforms, un miembro con el rol Administrador o Facturación puede ver cuánto le ha costado tu app a la organización este mes. También puede establecer un [tope de gasto](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#spend-caps) mensual para tu app y desvincularla. Todas las demás preguntas sobre tu app deben dirigirse a ti, así que indica a tus clientes cómo comunicarse contigo.

## Inicialización de los fragmentos de código

Los ejemplos de Python de esta página comparten la siguiente configuración, que escribes una sola vez. Define:

* las importaciones
* el ID de cliente y la URI de redirección de tu app
* el valor del encabezado beta de facturación
* un cliente de la Claude API que se autentica como tu cuenta de servicio
* `client_assertion`, que devuelve la aserción de cliente que tu back end envía a `auth.claude.com`

```python
# Los ejemplos de Python asumen la siguiente inicialización y variables
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"
# cópialo de platform.claude.com después de registrar tu app de 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 de API. El SDK intercambia el JWT de identidad de tu carga de trabajo por un token
# de acceso y lo renueva, así que nunca manejas "Bearer <access token>" tú mismo.
client = anthropic.Anthropic()

# Aserción de cliente para auth.claude.com: el propio JWT de identidad, leído de nuevo en
# cada llamada porque el archivo rota. Si la config. de autenticación de cliente de tu app
# indica una audiencia distinta a tu regla de federación, apunta esto a
# un segundo archivo de token: IdentityTokenFile("/path/to/other/token").
client_assertion = IdentityTokenFile()
```
