---
title: Referencia de OAuth
url: https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference
description: Endpoints, autenticación de cliente, parámetros de solicitud, alcances, respuestas de token, revocación, tiempos de vida, reglas de URI de redirección y errores.
---

<Warning>
  Claude Platform OAuth es un Beta Service: software previo al lanzamiento proporcionado bajo tu acuerdo con Anthropic, como los [Términos Comerciales de Servicio](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>

Esta página reúne los endpoints, los parámetros, las reglas de validación y las asignaciones de errores para [Claude Platform OAuth](https://platform.claude.com/docs/es/manage-claude/oauth-apps/overview). Para ver una guía paso a paso, consulta [Linked billing](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections).

## Endpoints

| Endpoint                                                                    | URL                                                                                |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Emisor                                                                      | `https://identity.anthropic.com/users`                                             |
| Documento de descubrimiento                                                 | `https://identity.anthropic.com/users/.well-known/openid-configuration`            |
| Claves de firma (JWKS)                                                      | El `jwks_uri` del documento de descubrimiento, alojado en `identity.anthropic.com` |
| Endpoint de autorización (página de inicio de sesión y consentimiento)      | `https://auth.claude.com/oauth/authorize`                                          |
| Endpoint de solicitud de autorización enviada (PAR)                         | `https://auth.claude.com/v1/oauth/par`                                             |
| Endpoint de token                                                           | `https://auth.claude.com/v1/oauth/token`                                           |
| Endpoint de revocación                                                      | `https://auth.claude.com/v1/oauth/revoke`                                          |
| Claude API (perfiles de usuario y solicitudes que se facturan a un cliente) | `https://api.anthropic.com`                                                        |

Lee las claves de firma del “discovery document” (documento de descubrimiento) en lugar de codificarlas de forma fija. El documento de descubrimiento no incluye el endpoint PAR ni el endpoint de revocación, así que usa las URL de esta tabla.

## Valores del documento de descubrimiento

| Campo                                   | Valor                                            |
| --------------------------------------- | ------------------------------------------------ |
| `issuer`                                | `https://identity.anthropic.com/users`           |
| `authorization_endpoint`                | `https://auth.claude.com/oauth/authorize`        |
| `token_endpoint`                        | `https://auth.claude.com/v1/oauth/token`         |
| `jwks_uri`                              | `https://identity.anthropic.com/users/jwks.json` |
| `response_types_supported`              | `code`                                           |
| `grant_types_supported`                 | `authorization_code`, `refresh_token`            |
| `code_challenge_methods_supported`      | `S256`                                           |
| `token_endpoint_auth_methods_supported` | `private_key_jwt`                                |
| `id_token_signing_alg_values_supported` | `ES256`                                          |
| `scopes_supported`                      | `openid`, `email`                                |
| `subject_types_supported`               | `public`, `pairwise`                             |

`auth.claude.com` devuelve un token de actualización para Linked billing solo cuando el cliente aprobó `offline_access` junto con `billing:attribution`: consulta [Tokens de OAuth para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection).

## Autenticación de cliente

`auth.claude.com` autentica un cliente confidencial con el método `private_key_jwt` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)). Envía estos parámetros en cada solicitud al endpoint PAR, al endpoint de token y al endpoint de revocación. Nunca envíes credenciales en la cadena de consulta de una URL: `auth.claude.com` las rechaza.

| Parámetro               | Valor                                                                                                                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`             | El ID de cliente de tu app de OAuth                                                                                                                                                            |
| `client_assertion_type` | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`                                                                                                                                       |
| `client_assertion`      | Un JWT de tu proveedor de identidad con los claims de [Claims de la aserción de cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-assertion-claims) |

### Claims de la aserción de cliente

Una “client assertion” (aserción de cliente) debe contener todos los siguientes claims, y su encabezado debe contener el `kid` de una clave en tu JWKS.

| Claim | Requisito                                                                                                                                                                                            |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss` | La URL del emisor de tu proveedor de identidad, exactamente como se registró mediante [Workload Identity Federation](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation) |
| `sub` | Un valor que coincida con el patrón de sujeto de la configuración de autenticación de cliente de tu app, si estableciste uno                                                                         |
| `aud` | Exactamente una audiencia: el valor de la configuración de autenticación de cliente de tu app. `auth.claude.com` rechaza una aserción que incluya más de una audiencia.                              |
| `iat` | El momento en que tu proveedor de identidad emitió el JWT                                                                                                                                            |
| `exp` | El momento de expiración, no más de 1 hora después de `iat`. Usa un tiempo de vida más corto cuando puedas: cualquiera que intercepte una aserción puede usarla hasta que expire.                    |

Ejemplo de payload de aserción:

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

Haz que el patrón de sujeto y las condiciones de los claims sean tan restringidos como lo permita tu back end. `auth.claude.com` acepta cualquier JWT de tu proveedor de identidad que coincida con ellos como autenticación de tu app.

## Parámetros de la solicitud de autorización

Envía estos parámetros, excepto `request_uri`, en el cuerpo JSON de una “pushed authorization request” (solicitud de autorización enviada).

| Parámetro                | Linked billing | Descripción                                                                                                                                                                                               |
| ------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type`          | Obligatorio    | El valor `code`                                                                                                                                                                                           |
| `client_id`              | Obligatorio    | El ID de cliente de tu app de OAuth                                                                                                                                                                       |
| `redirect_uri`           | Obligatorio    | Un URI que coincida exactamente con un URI de redirección registrado, de hasta 2048 caracteres                                                                                                            |
| `scope`                  | Obligatorio    | Para una conexión de facturación, `billing:attribution` o `billing:attribution offline_access`. Consulta [Alcances](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#scopes). |
| `state`                  | Obligatorio    | Un valor aleatorio de un solo uso, de hasta 2048 caracteres, que verificas en el callback                                                                                                                 |
| `code_challenge`         | Obligatorio    | `BASE64URL(SHA256(code_verifier))`, donde el `code_verifier` tiene entre 43 y 128 caracteres                                                                                                              |
| `code_challenge_method`  | Obligatorio    | El valor `S256`                                                                                                                                                                                           |
| `connection_type`        | Obligatorio    | El valor `organization_shared`. Este valor solicita una conexión de organización para facturación.                                                                                                        |
| `connection_auth_target` | Obligatorio    | A qué organización se enrutan las solicitudes de la conexión. Para Linked billing, envía `platform` (el propietario de la app de OAuth).                                                                  |
| `user_profile_id`        | Obligatorio    | El ID de un perfil de usuario activo en tu organización que representa al cliente                                                                                                                         |
| `request_uri`            | Obligatorio    | El valor que devolvió el endpoint PAR. Envíalo al endpoint de autorización con `client_id` y ningún otro parámetro.                                                                                       |

El endpoint PAR devuelve HTTP 201 con `request_uri` y `expires_in` (600 segundos).

## Alcances

| Categoría   | Alcance                   | Descripción                                                                                                                                                                                                                                                                                                                                                                                                                     | Tipo de conexión      | Tipo de cliente |
| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------- |
| General     | `offline_access`          | Da a la app un token de actualización que representa los demás alcances solicitados. En una conexión `organization_shared`, envíalo solo junto con `billing:attribution`.                                                                                                                                                                                                                                                       | `organization_shared` | Confidencial    |
| Facturación | `billing:attribution`     | Una conexión que te permite facturar a la organización de Claude de un cliente las solicitudes a la Claude API que ese cliente te indique realizar. Envíalo solo, o junto con `offline_access` para obtener también un token de actualización. Consulta [Tokens de OAuth para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). | `organization_shared` | Confidencial    |
| Facturación | `org:billing_attribution` | Obsoleto: usa `billing:attribution`.                                                                                                                                                                                                                                                                                                                                                                                            | `organization_shared` | Confidencial    |

## Solicitud y respuesta de token

Envía las solicitudes de token a `https://auth.claude.com/v1/oauth/token` con un cuerpo JSON.

| Parámetro                                                | Valor                                                                                                                                  |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`                                             | `authorization_code`                                                                                                                   |
| `code`                                                   | El código del callback                                                                                                                 |
| `redirect_uri`                                           | El mismo `redirect_uri` que enviaste en la solicitud de autorización                                                                   |
| `code_verifier`                                          | El verificador de código de PKCE                                                                                                       |
| `client_id`, `client_assertion_type`, `client_assertion` | Como en [Autenticación de cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-authentication) |

La respuesta de token contiene estos campos:

| Campo de respuesta         | Linked billing                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`             | [El token de acceso de la conexión](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection) |
| `token_type`               | `Bearer`                                                                                                                                                |
| `expires_in`               | Como máximo `3600`                                                                                                                                      |
| `scope`                    | `workspace:inference`                                                                                                                                   |
| `connection_id`            | El ID de la conexión, por ejemplo `ocon_EXAMPLE`. Guárdalo.                                                                                             |
| `refresh_token`            | Se devuelve solo cuando el cliente aprobó `offline_access`                                                                                              |
| `refresh_token_expires_in` | Segundos hasta que expire `refresh_token`. Ausente cuando no hay `refresh_token`.                                                                       |

Para renovar, envía `grant_type` establecido en `refresh_token`, tu `refresh_token` y los parámetros de [Autenticación de cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-authentication). Una renovación de una conexión de facturación sigue las reglas de [Tokens de OAuth para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection).

## Tokens de OAuth para una conexión de facturación

Para una conexión de facturación, el endpoint de token devuelve el token de acceso de la conexión. El token se autentica como la [cuenta de servicio operadora](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#terms) de tu app, en el espacio de trabajo que indica la configuración `connection_token_workspace_id` de la app. En `/v1/messages` y `/v1/chat/completions`, una solicitud con este token se factura al cliente de esa conexión y a nadie más. Cuando el cliente también aprobó `offline_access`, el endpoint de token devuelve además un token de actualización, y la concesión `refresh_token` renueva ambos tokens. Para la configuración y la guía paso a paso, 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) en la página de Linked billing.

Ambas concesiones usan los parámetros de [Solicitud y respuesta de token](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#token-request-and-response), con [Autenticación de cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-authentication). Una renovación no debe enviar un parámetro `scope`. La respuesta de token contiene estos campos:

| Campo de respuesta         | Valor                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `access_token`             | El token de acceso de la conexión                                                                     |
| `token_type`               | `Bearer`                                                                                              |
| `expires_in`               | Segundos hasta que expire el token de acceso, como máximo `3600`                                      |
| `scope`                    | Siempre `workspace:inference`                                                                         |
| `connection_id`            | El ID de la conexión, por ejemplo `ocon_EXAMPLE`. Solo la concesión `authorization_code` lo devuelve. |
| `refresh_token`            | El token de actualización de la conexión. Se devuelve solo cuando el cliente aprobó `offline_access`. |
| `refresh_token_expires_in` | Segundos hasta que expire `refresh_token`                                                             |

Cada renovación devuelve un nuevo `access_token` y un nuevo `refresh_token`. El token de actualización que enviaste queda reemplazado, y el token de acceso anterior deja de funcionar en unos pocos minutos. Puedes enviar el token de actualización reemplazado una vez más, dentro de los 30 segundos posteriores a la renovación que lo reemplazó, para repetir una solicitud cuya respuesta perdiste. Esa segunda solicitud devuelve otro par nuevo y revoca el par de la respuesta perdida: usa solo el par más reciente. Una tercera solicitud con el token reemplazado recibe `invalid_grant`, y lo mismo ocurre con una segunda solicitud que llega después de los 30 segundos. Dentro de los 30 segundos, una solicitud así no revoca nada. Pasados los 30 segundos, revoca todos los tokens de la conexión y finaliza la conexión. [Actualiza los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) contiene las reglas y los errores de una renovación.

Cada uno de estos eventos revoca los tokens de la conexión, incluido el token de acceso actual:

* El cliente o tú desvinculan la conexión.
* El cliente aprueba una nueva solicitud de autorización con alcances diferentes para el mismo perfil de usuario, y tú intercambias el código de esa aprobación. La nueva conexión reemplaza a la anterior.
* Se archiva el espacio de trabajo en el que operan los tokens.

Para saber cómo factura la Claude API una solicitud con el token de acceso de una conexión, 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).

## Revocación

Envía las solicitudes de revocación a `https://auth.claude.com/v1/oauth/revoke` con un cuerpo JSON o codificado como formulario. El endpoint sigue [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) y también acepta IDs de conexión y de perfil de usuario.

Envía los parámetros de [Autenticación de cliente](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#client-authentication) y exactamente uno de los parámetros de esta tabla. El `aud` de la aserción de cliente es el valor de la configuración de autenticación de cliente de tu app, no la URL de revocación.

| Parámetro         | Qué finaliza                                                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_id`   | Una de las conexiones de tu app, indicada como un ID `ocon_`                                                                           |
| `user_profile_id` | Todas las conexiones de tu app en un perfil de usuario, indicado como un ID `uprof_`                                                   |
| `token`           | Para Linked billing, envía `connection_id` o `user_profile_id` en su lugar: enviar un token de acceso podría no finalizar la conexión. |

`auth.claude.com` acepta `token_type_hint` y lo ignora.

El endpoint devuelve HTTP 200 y los IDs de las conexiones que finalizó la solicitud:

```json
{
  "revoked_connection_ids": ["ocon_EXAMPLE"]
}
```

La lista está vacía si el token o el ID es desconocido o pertenece a otra app, si la conexión ya finalizó, o si la solicitud finalizó un token pero ninguna conexión. La respuesta no indica cuál.

Después de que finaliza una conexión de facturación, la Claude API rechaza las solicitudes que se facturan a ese cliente, con `user_profile_not_billable`, y los tokens de OAuth de la conexión dejan de funcionar. A partir de ese momento, no dependas de un token de acceso de una conexión aprobada con el alcance obsoleto `org:billing_attribution`: podría dejar de funcionar de inmediato o funcionar hasta que expire.

## Tiempos de vida

| Elemento                       | Tiempo de vida                                                              |
| ------------------------------ | --------------------------------------------------------------------------- |
| `request_uri` del endpoint PAR | 10 minutos, un solo uso                                                     |
| Código de autorización         | 5 minutos, un solo uso                                                      |
| `access_token`                 | Hasta 1 hora                                                                |
| `refresh_token`                | Hasta 1 año desde el intercambio del código. Una renovación no lo extiende. |

Estos son los valores actuales. Lee `expires_in` y `refresh_token_expires_in` de cada respuesta en lugar de depender de valores fijos.

## Reglas de URI de redirección

* Cada `redirect_uri` debe coincidir exactamente con un URI registrado en tu app. `auth.claude.com` no usa coincidencia con comodines ni por prefijo.
* Todo URI de redirección debe usar HTTPS y no debe contener un fragmento. Los URI de desarrollo local en `localhost`, `127.0.0.1` o `[::1]` pueden usar HTTP.
* Un URI de desarrollo local registrado con un asterisco como puerto, como `http://localhost:*/callback`, coincide con cualquier puerto.
* Puedes registrar hasta 10 URI de redirección por app.
* `auth.claude.com` envía errores a tu URI de redirección solo cuando el `redirect_uri` coincide con un URI registrado. Para cualquier otro `redirect_uri`, `auth.claude.com` no redirige el navegador.

## Errores

### Errores en la redirección

`auth.claude.com` devuelve los errores como parámetros de consulta `error`, `error_description` y `state` en tu URI de redirección. Son errores estándar de OAuth 2.0 ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749)), excepto `user_profile_already_linked`, que es específico de Anthropic.

| Error                         | Cuándo                                                                                                                                                                                                                                                                  | Qué mostrarle a tu usuario                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `access_denied`               | La persona rechazó la solicitud, o no puede aprobarla. Para una conexión de facturación, la persona debe ser administrador de una organización de Claude.                                                                                                               | Explica que la conexión no se completó, y no asumas que la persona la rechazó. Para una conexión de facturación, sigue [Tu URI de redirección recibe `error=access_denied`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#access-denied) en la guía de Linked billing, que enumera las causas y qué decirle a la persona. De lo contrario, pídele a la persona que se ponga en contacto contigo. |
| `server_error`                | `auth.claude.com` no pudo procesar la solicitud.                                                                                                                                                                                                                        | Pide al usuario que lo intente de nuevo.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `user_profile_already_linked` | Solo Linked billing. La organización del cliente ya está vinculada a tu app a través de un perfil de usuario diferente. Cada organización cliente puede tener una conexión con tu app. `auth.claude.com` ya le pidió al administrador que se ponga en contacto contigo. | Explica que su organización ya está vinculada a tu app.                                                                                                                                                                                                                                                                                                                                                                                          |

Si el `request_uri` expiró o ya lo usaste, `auth.claude.com` muestra una página de error y no redirige el navegador de vuelta a tu app. Inicia el flujo de nuevo con una nueva solicitud de autorización enviada.

### Errores de los endpoints PAR y de token

Estos endpoints devuelven un cuerpo JSON con `error` y `error_description`.

| Error                         | Cuándo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`             | Falta un parámetro obligatorio o no es válido, por ejemplo falta `state` o el desafío PKCE, o un `user_profile_id` no es el ID de un perfil de usuario activo en tu organización.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `invalid_client`              | `auth.claude.com` no pudo autenticar tu app: el ID de cliente es desconocido o la aserción de cliente no superó la verificación. Compara los valores `iss`, `sub` y `aud` de la aserción con la configuración de autenticación de cliente de tu app, y verifica que tu proveedor de identidad la haya firmado con una clave de tu JWKS.                                                                                                                                                                                                                                                                                                                                                             |
| `invalid_scope`               | El alcance solicitado no está permitido para esta app o este tipo de conexión. Para los [tokens de una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection), esto también significa que una renovación envió un parámetro `scope`, que no acepta, o que `billing:attribution` ya no está registrado para tu app. En el intercambio del código, esa segunda causa consume el código.                                                                                                                                                                                                                         |
| `invalid_grant`               | El código expiró, ya lo usaste o no coincide con el `redirect_uri` o el `code_verifier`. Para una renovación, el token de actualización expiró o ya no es válido: sigue [Actualiza los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).                                                                                                                                                                                                                                                                                                                                                                               |
| `unauthorized_client`         | Tu app no está configurada para esta solicitud. Para Linked billing, revisa primero la cuenta de servicio operadora de la app y su espacio de trabajo: 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). Para los [tokens de una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection), `error_description` indica la causa, por ejemplo que falta un espacio de trabajo. Este rechazo no consume ningún código ni revoca ningún token de actualización. |
| `user_profile_already_linked` | Solo Linked billing, desde el endpoint de token. Entre la aprobación y esta solicitud, el perfil de usuario se vinculó a tu app a través de una organización cliente diferente, o la organización del cliente se vinculó a través de un perfil de usuario diferente.                                                                                                                                                                                                                                                                                                                                                                                                                                |

Si `auth.claude.com` aplica un “rate limit” (límite de velocidad) a una solicitud, sufre una interrupción o recibe un `grant_type` desconocido o un parámetro que supera su límite de longitud, devuelve un error en un formato diferente, que podría no ser JSON. Reintenta solo con respuestas HTTP 429 y 5xx, con backoff. Trata cualquier otro estado como un fallo en la solicitud. Para una renovación de una conexión de facturación, sigue [Actualiza los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) en lugar de un backoff general. Si la respuesta tiene un encabezado `retry-after`, espera al menos ese tiempo. Envía la siguiente solicitud desde tu propio código y no dependas de los reintentos automáticos de una biblioteca cliente HTTP: es posible que no se ejecuten para una respuesta así. [Actualiza los tokens](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) también indica cuándo es seguro reintentar, porque un token de actualización que ya se usó puede finalizar la conexión cuando lo envías de nuevo.

### Errores del endpoint de revocación

Para la mayoría de las solicitudes que `auth.claude.com` rechaza, el endpoint de revocación devuelve HTTP 400 y un cuerpo JSON con `error` y `error_description`.

| Error                 | Cuándo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `invalid_request`     | Falta un parámetro obligatorio o no es válido, por ejemplo falta `client_id`. La solicitud no envía ninguno de `token`, `connection_id` y `user_profile_id`, o envía más de uno. Un ID tiene un formato incorrecto, por ejemplo tiene el prefijo equivocado. Una credencial o `token` está en la cadena de consulta de la URL. El perfil de usuario tiene demasiadas conexiones para una sola solicitud: es posible que la solicitud haya finalizado algunas, así que finaliza el resto con `connection_id`. |
| `invalid_client`      | `auth.claude.com` no pudo autenticar tu app. Para saber qué revisar, consulta `invalid_client` en [Errores de los endpoints PAR y de token](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#errors-from-the-par-and-token-endpoints).                                                                                                                                                                                                                                           |
| `unauthorized_client` | Tu app no está configurada para esta solicitud. Ponte en contacto con tu equipo de cuenta de Anthropic.                                                                                                                                                                                                                                                                                                                                                                                                      |

Las respuestas de la siguiente tabla usan un formato diferente, que podría no ser JSON. Cuando el cuerpo es JSON, `error` es un objeto, no una cadena.

| Estado | Cuándo                                                          | Qué hacer                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Un parámetro supera su límite de longitud.                      | Corrige la solicitud. No reintentes.                                                                                                                                                                                                                                                                                                                                                                                |
| 429    | Llegaron demasiadas solicitudes fallidas desde tu dirección IP. | Reintenta con backoff.                                                                                                                                                                                                                                                                                                                                                                                              |
| 500    | `auth.claude.com` no pudo procesar la solicitud.                | Reintenta con backoff. Si sigue ocurriendo, ponte en contacto con tu equipo de cuenta de Anthropic.                                                                                                                                                                                                                                                                                                                 |
| 501    | Anthropic no ha habilitado este endpoint para tu organización.  | No reintentes. Ponte en contacto con tu equipo de cuenta de Anthropic.                                                                                                                                                                                                                                                                                                                                              |
| 503    | La solicitud no terminó. Todo lo que finalizó sigue finalizado. | Reintenta con backoff, con los mismos parámetros y una nueva aserción de cliente. El reintento completa el resto, y su lista omite las conexiones que finalizó la solicitud anterior. Si enviaste `user_profile_id`, reintenta en un plazo de un día: después de eso, un reintento puede devolver 200 con una lista vacía y no completar nada. Un reintento con cada `connection_id` funciona en cualquier momento. |

### Errores de facturación

Estos se aplican a las solicitudes a la Claude API que establecen `billing_policy.bill_to` en `"user_profile"` o que se autentican con [el token de acceso de una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). La Claude API no factura a ninguna de las dos organizaciones por una solicitud rechazada. Ninguna de las respuestas 402 y 403 se puede reintentar, excepto un rechazo `user_profile_not_billable` en los primeros 10 segundos después de una nueva conexión.

| Estado | Tipo y código de error                                     | Cuándo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request_error`                                    | La solicitud envía `billing_policy` sin el encabezado beta `user-profiles-billing-2026-10-01`. O al objeto `billing_policy` le falta un campo o tiene un campo no válido. Con el token de acceso de una conexión de facturación, se puede omitir `bill_to`. O la solicitud usa ejecución de código fuera de la combinación permitida.                                                                                                                                                                                                                                                                                                                                                                       |
| 400    | `invalid_request_error`, `user_profile_required`           | `bill_to` es `"user_profile"`, la solicitud no incluye un ID de perfil de usuario y no se autentica con el token de acceso de una conexión de facturación.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 400    | `invalid_request_error`, sin código de error               | La solicitud se autentica con el token de acceso de una conexión de facturación y, o bien establece `bill_to` en `"self"`, o bien indica un perfil de usuario distinto de aquel al que está limitado el token. Cada uno de estos dos rechazos indica qué está mal en `error.message`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 401    | `authentication_error`                                     | La solicitud se autentica con el token de acceso de una conexión de facturación que expiró, que una renovación reemplazó o cuya conexión finalizó. El mensaje indica si el token expiró o fue revocado. Envía la solicitud de nuevo con el token de acceso actual, o vincula al cliente de nuevo si la conexión finalizó. Después de que una conexión finaliza, cada nueva solicitud con su token de acceso puede recibir este 401 o un 403 `user_profile_not_billable`, sin un orden fijo.                                                                                                                                                                                                                 |
| 402    | `billing_error`, `linked_organization_spend_limit_reached` | La organización cliente alcanzó un límite de gasto que estableció para tu app de OAuth o para 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. Pide al cliente que revise ambos límites y su saldo de crédito. La sección [Errores esperados](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#expected-errors) para Linked billing indica dónde se establece cada uno y qué cambiar.                                                                                                                                                              |
| 402    | `billing_error`, `linked_organization_billing_unavailable` | Anthropic no puede facturar actualmente a la organización cliente debido a un problema con la propia cuenta de Anthropic de esa organización. El mismo código finaliza una respuesta que Claude ya había comenzado cuando se agota el crédito de la organización. Pide al cliente que revise su estado de facturación con Anthropic.                                                                                                                                                                                                                                                                                                                                                                        |
| 403    | `permission_error`, sin código de error                    | Anthropic no factura directamente a tu organización, por lo que no puede facturar a los clientes en tu nombre.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 403    | `permission_error`, `user_profile_not_billable`            | El perfil de usuario no tiene conexión con una organización cliente, un administrador o tu back end finalizó la conexión, la organización cliente no paga directamente a Anthropic por su uso de la API (cuentan tanto los créditos prepagados como la facturación mediante factura), o la solicitud no se autentica como la cuenta de servicio de tu app. La respuesta no indica cuál. El token de acceso de una conexión también puede recibirlo después de que la conexión haya finalizado. La sección [Causas de `user_profile_not_billable`](https://platform.claude.com/docs/es/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable) indica qué revisar en cada caso. |
| 503    | `overloaded_error`                                         | La Claude API no puede confirmar temporalmente si puede facturar al cliente. Reintenta la solicitud. Si la respuesta incluye un encabezado `retry-after`, espera ese tiempo antes de reintentar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

En `/v1/messages`, el código de error está en `error.details.error_code`. En `/v1/chat/completions`, `error.type` siempre es `invalid_request_error`, `error.code` contiene el tipo de error de Anthropic (por ejemplo `permission_error` o `billing_error`) y la respuesta no tiene código de error, así que identifica el error por el estado HTTP y `error.code`.

## Estándares

| Estándar                                                                                  | Dónde se aplica                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [OAuth 2.0 (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749)                            | Flujo de código de autorización, endpoint de token y respuestas de error                                                                                                                            |
| [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)                                 | Obligatorio con `S256` en cada solicitud de autorización                                                                                                                                            |
| [Solicitudes de autorización enviadas (RFC 9126)](https://www.rfc-editor.org/rfc/rfc9126) | Obligatorio para Linked billing.                                                                                                                                                                    |
| [Revocación de tokens (RFC 7009)](https://www.rfc-editor.org/rfc/rfc7009)                 | El endpoint de revocación, que también acepta IDs de conexión y de perfil de usuario y devuelve los IDs de las conexiones que finalizó                                                              |
| [Autenticación de cliente JWT (RFC 7523)](https://www.rfc-editor.org/rfc/rfc7523)         | La autenticación de cliente `private_key_jwt` en los endpoints PAR, de token y de revocación, y el intercambio de tokens de la cuenta de servicio para las solicitudes que se facturan a un cliente |

## Términos usados en estas páginas

Los siguientes significados se aplican solo a Claude Platform OAuth.

| Término                                 | Significado                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organización de Claude                  | Una cuenta de organización con Anthropic. Tu empresa tiene una, y también cada cliente que vincula su organización para facturación.                                                                                                                                                                                                                                                                                                                                                              |
| Administrador                           | Un miembro de una organización de Claude con el rol Administrador o Facturación.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| App de OAuth                            | El registro en tu organización de Claude que identifica tu producto ante `auth.claude.com`. Tiene un ID de cliente, un nombre, un logotipo, una URL de página de inicio, URI de redirección y los tipos de conexión que admite.                                                                                                                                                                                                                                                                   |
| Tipo de conexión                        | Quién aprueba una conexión: un administrador en nombre de toda una organización (`organization_shared`, para Linked billing).                                                                                                                                                                                                                                                                                                                                                                     |
| Proveedor de identidad                  | El servicio en tu propia infraestructura que firma JWT de corta duración para tu back end y publica sus claves públicas como un JSON Web Key Set (JWKS), como el servicio de identidad de cargas de trabajo de tu proveedor de nube o tu propio emisor compatible con OIDC. En estas páginas, “tu proveedor de identidad” siempre se refiere a este servicio, no a Anthropic.                                                                                                                     |
| Aserción de cliente                     | Un JWT de corta duración que tu proveedor de identidad firma y que tu back end envía para autenticar tu app de OAuth. Este es el método de autenticación de cliente `private_key_jwt` (RFC 7523).                                                                                                                                                                                                                                                                                                 |
| Solicitud de autorización enviada (PAR) | Una solicitud en la que tu back end envía los parámetros de autorización directamente a `auth.claude.com` y recibe un `request_uri` para usar en la redirección del navegador (RFC 9126).                                                                                                                                                                                                                                                                                                         |
| Workload Identity Federation            | La función de Claude Console mediante la cual tu organización registra tu proveedor de identidad, para que Anthropic acepte los JWT firmados con las claves de tu JWKS.                                                                                                                                                                                                                                                                                                                           |
| Documento de descubrimiento             | El documento OIDC que enumera el emisor, los endpoints y las claves de firma de Anthropic.                                                                                                                                                                                                                                                                                                                                                                                                        |
| Perfil de usuario                       | Un registro que creas en tu propia organización de Claude para representar a uno de tus clientes. Una conexión de facturación vincula un perfil de usuario con la organización de Claude del cliente.                                                                                                                                                                                                                                                                                             |
| Cuenta de servicio                      | Una cuenta no humana en tu organización de Claude. Para Linked billing, tu app de OAuth está vinculada a una cuenta de servicio, su cuenta de servicio operadora, y tu back end se autentica como esa cuenta de servicio cuando envía una solicitud que se factura a un cliente.                                                                                                                                                                                                                  |
| Tokens de OAuth de la conexión          | El token de acceso que `auth.claude.com` devuelve para una conexión de facturación, y el token de actualización que devuelve cuando el cliente también aprobó `offline_access`. El token de acceso se autentica como la cuenta de servicio operadora y solo puede facturar al perfil de usuario de esa conexión. Consulta [Tokens de OAuth para una conexión de facturación](https://platform.claude.com/docs/es/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). |
