Claude Platform Docs
AdministraciónClaude Platform OAuth

Linked billing

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.

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

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 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 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 y esté activa, la configuración muestra Any Claude user.

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.

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.

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. Antes de vincular clientes, configura un “workspace” (espacio de trabajo) 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.

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.

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.

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_idVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. 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. 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). 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.

Navegador
Tu back end
auth.claude.com
Haz clic en “Link your Claude organization”
5
Solicitud de autorización enviada con el ID del perfil de usuario y una aserción de cliente
request_uri
6
Redirige a la página de aprobación (el endpoint de autorización)
7
El usuario inicia sesión en Claude, elige la organización y aprueba
Redirige a tu URI de redirección con un código de un solo uso y el state
Entrega el código y el state
Comprueba que el state coincida
8
Solicitud de token con el código, el verificador de código PKCE y una aserción de cliente
connection_id
Almacena el ID de conexión en el registro del cliente

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.

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

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.

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

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.
def push_authorization_request(user_profile_id: str) -> dict:
    state = secrets.token_urlsafe(32)
    code_verifier = secrets.token_urlsafe(64)
    code_challenge = create_s256_code_challenge(code_verifier)

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

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


par = push_authorization_request(user_profile_id)

auth.claude.com responde 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 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.

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.

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

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.

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.

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

La respuesta contiene el ID de conexión y el token de acceso de la conexión, 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 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 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. Consulta Actualiza las llamadas a Claude y Errores esperados 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.

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.
  • 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 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 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 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.
    • 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, 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ónDóndeSolución
La app tiene una cuenta de servicio operadoraOperator service account en la pestaña Client authentication de la appSelecciona 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á archivadoConfigura tu appElige 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 y Actualiza los tokens.

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

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.

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

Si la solicitud se rechaza, consulta Errores esperados.

Tú pagas

Para pagar tú, omite por completo billing_policy (en cuyo caso el encabezado beta de facturación es opcional):

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

o usa bill_to: "self":

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

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

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.

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.

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.

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

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, 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, 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.
  • 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 de tu app. No envíes un parámetro scope.

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


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


def is_lost(response: httpx.Response) -> bool:
    """True for a 5xx response that can follow a refresh that took effect."""
    if response.status_code < 500:
        return False
    # 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

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

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:

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.

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

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. 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
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 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 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 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, 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 o a su endpoint de costos. 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. Topes de gasto 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 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, 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.

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

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 para conocer los demás parámetros y Errores del endpoint de revocación.

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 describe lo que ve tu cliente, y Correos electrónicos sobre la vinculación y la desvinculación 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. De lo contrario, desvincula al cliente, como se describe en Desvincular a un cliente. El perfil de usuario se muestra entonces como Unlinked en tu página User profiles.
  2. Ejecuta de nuevo los Pasos 5 a 8 con el mismo perfil de usuario. Para el Paso 7, 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 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: 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 del estado 403, que es PermissionDeniedError. 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 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, 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, puede aumentarlo.
    • El saldo de crédito: En su página Facturación, 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.
  • 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.
  • 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.

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 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 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. 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, 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.
  • La organización del cliente. Debe ser un cliente elegible. 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 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. Esta pantalla es diferente mientras tu app está en pruebas: consulta Mientras tu app está en pruebas.
  • 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 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). El perfil de usuario del cliente aparece como Unlinked en tu página User profiles de la Console. Para volver a vincularse, ejecuta de nuevo los Pasos 5 a 8 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). 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. 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 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. 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 aprobadaDespués de que la app está publicada
Un límite de gasto mensual en la página de aprobaciónObligatorio, de $50 USD o menosOpcional
El campo del monto en la página de aprobaciónComienza en $50 USDComienza vacío
Continue without a limit en la página de aprobaciónNo se ofreceSe ofrece
Eliminar el tope en la ConsoleNo es posibleEs posible
El tope más grande que puede establecer un cliente$50 USDSin 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 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
# 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()

¿Te resultó útil esta página?