Perfiles de usuario para la atribución a clientes finales

Los "user profiles" (perfiles de usuario, o "perfiles") le indican a Anthropic para cuál de tus clientes finales es cada solicitud de API. Así, una medida de aplicación por motivos de seguridad, como una retención o un bloqueo, puede aplicarse a un solo cliente final en lugar de a toda tu organización. Cuando esto ocurre, el resto de tu tráfico no se ve afectado.

Si operas una plataforma o un gateway, o revendes acceso a la API, las solicitudes que envías para tus clientes finales llegan bajo tu organización. Anthropic ejecuta clasificadores de seguridad automatizados sobre el tráfico de la API. Sin un perfil en la solicitud, un solo cliente final puede desencadenar una medida de aplicación que se aplique a toda tu organización.

Registras a cada cliente final una vez con POST /v1/user_profiles y guardas el ID uprof_ que devuelve. Luego envías ese ID en el encabezado anthropic-user-profile-id en cada solicitud que hagas en nombre de ese cliente final.

Los perfiles no son facturables y no afectan los precios.

Decide quién recibe un perfil

Lo que representa un perfil depende de cómo vendes Claude: una persona que usa tu producto o una empresa a la que revendes acceso a la API. Estos dos casos cubren la mayoría de las plataformas. El campo access_type del perfil indica cuál aplica.

Qué contiene un perfil y cómo lo usa Anthropic

Un perfil contiene solo lo que envías sobre el cliente final, más cualquier estado de programa que Anthropic establezca. No contiene contenido de conversaciones. Anthropic usa los detalles que envías para atribuir solicitudes, para supervisar posibles abusos, para hacer cumplir la Política de Uso y para permitir la postulación y el acceso a programas de acceso de confianza. Anthropic no verifica los detalles.

Anthropic procesa los perfiles de acuerdo con la Política de privacidad.

Antes de comenzar

Creas y administras perfiles en uno de los siguientes:

• Una organización en la Claude API.
• Una organización en Claude Platform on AWS. La entidad principal que realiza la llamada necesita las acciones de IAM de perfiles de usuario.
• Una implementación de Microsoft Foundry alojada en Anthropic, no una alojada en Azure. No necesitas una organización en la Claude API ni en Claude Platform on AWS. Usa tu endpoint de Foundry, con la misma URL base y autenticación que usas para la inferencia.

Amazon Bedrock y Google Cloud no tienen los endpoints /v1/user_profiles. Si tu inferencia se ejecuta allí, crea tus perfiles en una organización en la Claude API o en Claude Platform on AWS. En Amazon Bedrock, los perfiles funcionan solo con Claude en Amazon Bedrock. Consulta Atribuye solicitudes en Amazon Bedrock y Google Cloud.

Mantén el tráfico que envías para tus clientes finales en una organización y tu propio uso interno en otra. Los perfiles pertenecen a una organización, no a un espacio de trabajo, así que no basta con espacios de trabajo separados en una misma organización. Solo la organización para el tráfico de clientes finales necesita perfiles de usuario. Para crear otra organización en la Claude API, consulta la sección "How to create a new organization" de Creating and managing Workspaces in the Claude Console en el Centro de ayuda de Claude.

Los ejemplos llaman a la Claude API con una clave de API. No necesitas una clave de API de administrador. En Claude Platform on AWS, usa su URL base y su autenticación.

Crea un perfil para cada cliente final

Crea un perfil para cada cliente final cuyo tráfico envíes a Claude. Créalo una sola vez, en tu flujo de incorporación de clientes. POST /v1/user_profiles no es idempotente, así que cada llamada crea un perfil nuevo, incluso cuando reference_id coincide con uno existente. Si ya tienes clientes finales sin perfiles, consulta las indicaciones sobre cómo registrar una base de clientes existente más adelante en esta sección.

El siguiente ejemplo registra una empresa que compra acceso a la API a través de un gateway, por lo que establece access_type en passthrough. Para un perfil application, omite access_type y describe a un usuario final en name y external_user_details en lugar de una empresa. Decide quién recibe un perfil compara los dos tipos de acceso.

client = anthropic.Anthropic()

profile = client.user_profiles.create(
    name="Acme Analytics, Inc.",
    access_type="passthrough",
    external_user_details={"reference_id": "cust-8f2a1c", "country": "US"},
)

print(profile.id)

La respuesta es el nuevo perfil:

{
  "type": "user_profile",
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "name": "Acme Analytics, Inc.",
  "access_type": "passthrough",
  "external_user_details": {
    "reference_id": "cust-8f2a1c",
    "onboarded_at": null,
    "account_status": null,
    "entity_type": null,
    "country": "US",
    "name_hash": null,
    "email_hash": null
  },
  "metadata": {},
  "programs": {
    "cyber": null,
    "efs": null
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

Guarda el id en tu registro de cliente y haz que tus instancias de servicio lo lean desde allí en lugar de crear su propio perfil. Recuperas, actualizas y eliminas un perfil mediante ese id. El campo programs es de solo lectura y la atribución no lo usa. Contiene el estado del cliente final en cada programa que gestiona Anthropic. Para saber qué significan sus valores, consulta qué programas se aplican a un perfil.

No hay un límite en la cantidad de perfiles de una organización, pero la creación de perfiles está sujeta a un "rate limit" (límite de velocidad). Antes de registrar una base de clientes existente de forma masiva, comunícate con tu equipo de cuenta de Anthropic.

Qué decirle a Anthropic sobre un cliente final

Todos los campos son opcionales. Puedes enviar name, metadata y estos campos en external_user_details: entity_type, country, reference_id, onboarded_at, account_status, name_hash y email_hash. La referencia Crear un perfil describe cada campo, con su tipo, formato y límite de longitud.

Sigue estas reglas al establecer los campos:

• Valores desconocidos: Si no conoces un valor, omítelo en lugar de enviar un marcador de posición. Puedes reemplazar un valor en external_user_details más adelante, pero no puedes borrarlo.
• Nombres de empresas: Para un perfil passthrough, envía el nombre legal de la empresa en name si lo conoces.
• País: En country, envía el país del cliente final, no el tuyo.
• Tu propio ID: En reference_id, envía tu propio identificador estable para el cliente final. No tiene que ser único.
• Nombres y direcciones de correo electrónico que no puedes compartir: Omite name y envía external_user_details.name_hash en su lugar. Para la dirección de correo electrónico, envía external_user_details.email_hash. Un perfil no tiene ningún campo para la dirección en sí.
• Hashes: Calcula los hashes tú mismo, con una función que elijas. Le muestran a Anthropic cuáles de tus perfiles comparten un nombre o una dirección de correo electrónico. Usa la misma función y la misma normalización de mayúsculas/minúsculas y espacios en blanco para cada perfil, porque solo coinciden los valores calculados de la misma manera.

Atribuye cada solicitud

Envía el ID del perfil en el encabezado anthropic-user-profile-id en cada solicitud que hagas en nombre del cliente final. Los SDK y la CLI tienen un argumento que envía el encabezado por ti: user_profile_id.

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    user_profile_id="uprof_011CZkZCu8hGbp5mYRQgUmz9",
)

print(message)

El encabezado funciona de la misma manera en las solicitudes de conteo de tokens, Message Batches y compatibilidad con el SDK de OpenAI. En un lote, se aplica a cada solicitud del lote.

La Claude API, Claude Platform on AWS y las implementaciones de Microsoft Foundry alojadas en Anthropic comprueban el ID en cada solicitud. Si el ID tiene un formato incorrecto o no pertenece a la organización que envía la solicitud, la API devuelve un 400 invalid_request_error. De forma predeterminada, estas plataformas aceptan un ID de perfil solo en solicitudes de la organización que creó el perfil. Esto significa que si envías tráfico bajo más de una organización, por ejemplo una en la Claude API y otra en Claude Platform on AWS, una solicitud de una organización que no creó el perfil recibe el mismo 400.

Message Batches es la excepción: al crear un lote solo se comprueba el formato del ID. Si un ID con formato correcto no pertenece a la organización que envía el lote, el lote se crea de todos modos, y luego cada solicitud en él falla con un resultado errored que contiene el mismo invalid_request_error.

Atribuye solicitudes en Amazon Bedrock y Google Cloud

Un ID de perfil de cualquiera de los dos tipos de acceso también funciona en Claude en Amazon Bedrock y en Google Cloud. No funciona con la integración anterior de Amazon Bedrock que llamas con InvokeModel o Converse. Usas las credenciales de tu organización de Anthropic solo para crear y administrar perfiles. La inferencia sigue usando tus credenciales existentes de AWS o Google Cloud.

En Claude en Amazon Bedrock, coloca el ID en el nivel superior del cuerpo de la solicitud:

{
  "model": "anthropic.claude-opus-5-5",
  "max_tokens": 1024,
  "user_profile_id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "messages": [{ "role": "user", "content": "Hello, Claude" }]
}

Vincula cada cuenta de AWS que envía solicitudes a Claude en Amazon Bedrock, y cada proyecto de Google Cloud que envía solicitudes en Google Cloud, a la organización de Anthropic que crea tus perfiles:

1. Un administrador o propietario de esa organización inicia la vinculación en el Verification Portal en portal.anthropic.com, en Linked accounts.
2. Alguien que pueda administrar IAM en la cuenta de AWS o en el proyecto de Google Cloud ejecuta un comando que proporciona el portal.
3. El administrador o propietario completa la verificación en el portal.

Los programas que se aplican a un perfil se aplican a las solicitudes de una cuenta solo después de que la cuenta esté vinculada y el portal la muestre como Linked. Esos programas incluyen aquellos para los que se aprueba la organización de un cliente final después de que el cliente final vincula el perfil a esa organización.

Claude en Amazon Bedrock y Google Cloud comprueban el formato del ID, pero no buscan el perfil. Rechazan un ID con formato incorrecto con un 400. Aceptan cualquier ID con formato correcto, así que una respuesta exitosa no confirma que el ID corresponda a un perfil. Una solicitud sin ID se procesa sin atribución y, si desencadena una medida de aplicación, la medida se aplica a toda tu organización.

Identifica a usuarios individuales dentro de una empresa

Un perfil passthrough identifica a una empresa, no a la persona que realiza la solicitud. Si una solicitud proviene de una persona identificable, envía también un identificador para esa persona en el campo metadata.user_id de la solicitud de Messages. Este es el propio objeto metadata de la solicitud, no el campo metadata del perfil. El identificador es opcional y ayuda a Anthropic a detectar el uso indebido por parte de una persona.

Mantén los perfiles actualizados

Actualiza un perfil cuando cambien los detalles o el estado de la cuenta del cliente final, y elimínalo cuando cierre su cuenta o te pida que borres sus datos.

Actualiza un perfil

POST /v1/user_profiles/{id} cambia solo los campos que envías. Por ejemplo, úsalo cuando una empresa cambia de marca o cuando suspendes una cuenta.

• name y access_type reemplazan el valor almacenado.
• Cada campo que envías en external_user_details reemplaza el valor almacenado. No puedes borrar un valor. La API rechaza null con un 400.
• metadata se combina clave por clave. Una clave que envías sobrescribe el valor almacenado, una cadena vacía elimina la clave y las claves que omites permanecen como están.

El siguiente ejemplo marca la cuenta como suspendida y elimina una clave de metadatos trial_cohort.

client = anthropic.Anthropic()

profile = client.user_profiles.update(
    "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    external_user_details={"account_status": "suspended"},
    metadata={"trial_cohort": ""},
)

print(profile)

Elimina un perfil

DELETE /v1/user_profiles/{id} elimina permanentemente un perfil y todo lo que proporcionaste para él, incluidos name, external_user_details y metadata. No elimina los registros de confianza y seguridad que Anthropic conserva sobre ese ID de perfil.

Elimina un perfil cuando un cliente final cierre su cuenta o te pida que borres sus datos. Antes de eliminar un perfil, deja de enviar su ID en las solicitudes de ese cliente final. Si el cliente final sigue contigo después de una solicitud de borrado, crea un perfil nuevo y cambia a su ID. Luego elimina el anterior.

client = anthropic.Anthropic()

deleted = client.user_profiles.delete("uprof_011CZkZCu8hGbp5mYRQgUmz9")

print(deleted.id)

La respuesta repite el ID con "type": "user_profile_deleted". Si una eliminación devuelve un error del servidor, vuelve a intentarla. Un 404 en el reintento significa que la primera eliminación se completó.

Después de una eliminación, los endpoints de perfiles devuelven un 404 para ese ID. Durante un máximo de unos 10 minutos, las solicitudes de inferencia que llevan el ID eliminado aún pueden tener éxito. Después de eso, las plataformas que comprueban el ID en cada solicitud rechazan la solicitud con un 400. Claude en Amazon Bedrock y Google Cloud no buscan los perfiles, así que siguen aceptándola.

Próximos pasos

La referencia de la API contiene los campos, tipos y límites de cada endpoint: Crear un perfil, Recuperar un perfil, Actualizar un perfil y Listar perfiles.

Si las aprobaciones de programas de un cliente final deben aplicarse cuando usa Claude a través de tu plataforma, consulta Envía a un cliente final un enlace al Verification Portal.