> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Asumir rol con identidad web > Intercambiar un token de identidad emitido por un proveedor de federación en el que confía esta plataforma por credenciales temporales. El resultado es la misma sesión de rol asumido `POST /v1/assume-role` mints, y se usa de la misma manera. Esta solicitud lleva **sin firma**, y es la única llamada de venta de credenciales que no lo hace. Un llamador federado no tiene todavía credenciales de Basaltic, para eso es el intercambio, por lo que el token en el cuerpo *es* la credencial que se presenta. Una firma enviada de todas formas se ignora, y no se toma nada del contexto de la solicitud: `role` y `account` se leen del cuerpo como cualquier otro campo. Eso no deja el punto final abierto. Dos puertas independientes tienen que pasar, y fallan de manera diferente. **El token debe verificarse.** Esto sucede antes de que se lea cualquier rol, por lo que un token falsificado nunca alcanza una directiva de confianza. La firma debe encadenar a una clave que el proveedor publica, la audiencia debe ser la que esta plataforma acepta, y `exp` debe ser en el futuro. Un firmante incorrecto, un token acuñado para otro consumidor y un token caducado responden todos `401` con el mismo mensaje — la respuesta no dice qué comprobación falló. **El rol tiene que estar de acuerdo.** Verificar el token establece quién está llamando; no otorga nada. El rol nombrado en `role` es asumible solo si su propia política de confianza admite esta identidad. Sus `principals` deben nombrar al proveedor de federación, escrito `crn:iam:::oidc-provider/` — el único caso en el que un principal de la política de confianza no es el CRN del propio llamador, porque una identidad federada no tiene CRN y lo que se confía es la fuente que lo garantiza. Cada entrada en `conditions` debe entonces mantenerse contra las declaraciones del token: `basalt:webidentity:Subject` lleva el `sub` del token y `basalt:webidentity:Audience` su `aud`, por lo que un rol puede vincular una identidad en lugar de aceptar todo lo que el proveedor emitirá. Una condición en una afirmación que el token no lleva falla cerrada. Por lo tanto, un rol cuya directiva de confianza no nombre a ningún proveedor no puede asumirse de esta manera, por bueno que sea el token. Esa es la línea entre los dos fallos: `401` significa que el token no es confiable, `403` significa que lo es y el rol aún no lo tendrá. Las credenciales vuelven con el alcance de `account`, llevando los permisos propios del rol. No hay ningún campo `policy` aquí — a diferencia de `POST /v1/assume-role`, una sesión federada no puede ser reducida en el momento del intercambio, por lo que las políticas adjuntas del rol son la concesión completa. Tamaño del papel en consecuencia. Debido a que no requiere credenciales, las solicitudes están limitadas por la velocidad por IP del cliente. En qué proveedores se confía es parte de la configuración de la propia plataforma. Todavía no hay una API para registrar un proveedor de identidad propio, por lo que esta operación está activa pero no tiene un proveedor externo cuyos tokens aceptaría; los roles que la usan hoy en día son administrados por la plataforma. Requiere **sin acción de IAM**. El acceso se decide por las propias reglas del punto final en lugar de por una política. Consulte la descripción anterior. ## OpenAPI ````yaml /es/api-reference/specs/iam.yaml post /v1/assume-role-with-web-identity openapi: 3.0.3 info: title: API de Basaltic IAM version: 1.0.0 description: > Administración de identidad y acceso de cuentas: cuentas de servicio, roles, directivas de cuenta y sesiones temporales con ámbito de cuenta. La autenticación y el inicio de sesión personal permanecen en IAM. Las organizaciones, cuentas, usuarios, grupos y directivas de organización se administran mediante la API de Workspace. Las funciones y las políticas personalizadas pertenecen a la cuenta seleccionada. Sus CRN globales usan una región vacía y el identificador de la cuenta propietaria.Las entradas de relación se clasifican una vez como CRN, UUID o nombre, sin fallback de sintaxis. AssumeRole resuelve la cuenta propietaria del rol de destino. El llamador necesita permiso de origen y el rol de destino debe confiar en el llamador; la sesión resultante usa solo los permisos del rol de destino, sujeto a límites y restricciones de sesión. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://iam.basaltic.sh description: Endpoint de API global security: - BearerAuth: [] paths: /v1/assume-role-with-web-identity: post: tags: - IAM summary: Asumir rol con identidad web description: > Intercambiar un token de identidad emitido por un proveedor de federación en el que confía esta plataforma por credenciales temporales. El resultado es la misma sesión de rol asumido `POST /v1/assume-role` mints, y se usa de la misma manera. Esta solicitud lleva **sin firma**, y es la única llamada de venta de credenciales que no lo hace. Un llamador federado no tiene todavía credenciales de Basaltic, para eso es el intercambio, por lo que el token en el cuerpo *es* la credencial que se presenta. Una firma enviada de todas formas se ignora, y no se toma nada del contexto de la solicitud: `role` y `account` se leen del cuerpo como cualquier otro campo. Eso no deja el punto final abierto. Dos puertas independientes tienen que pasar, y fallan de manera diferente. **El token debe verificarse.** Esto sucede antes de que se lea cualquier rol, por lo que un token falsificado nunca alcanza una directiva de confianza. La firma debe encadenar a una clave que el proveedor publica, la audiencia debe ser la que esta plataforma acepta, y `exp` debe ser en el futuro. Un firmante incorrecto, un token acuñado para otro consumidor y un token caducado responden todos `401` con el mismo mensaje — la respuesta no dice qué comprobación falló. **El rol tiene que estar de acuerdo.** Verificar el token establece quién está llamando; no otorga nada. El rol nombrado en `role` es asumible solo si su propia política de confianza admite esta identidad. Sus `principals` deben nombrar al proveedor de federación, escrito `crn:iam:::oidc-provider/` — el único caso en el que un principal de la política de confianza no es el CRN del propio llamador, porque una identidad federada no tiene CRN y lo que se confía es la fuente que lo garantiza. Cada entrada en `conditions` debe entonces mantenerse contra las declaraciones del token: `basalt:webidentity:Subject` lleva el `sub` del token y `basalt:webidentity:Audience` su `aud`, por lo que un rol puede vincular una identidad en lugar de aceptar todo lo que el proveedor emitirá. Una condición en una afirmación que el token no lleva falla cerrada. Por lo tanto, un rol cuya directiva de confianza no nombre a ningún proveedor no puede asumirse de esta manera, por bueno que sea el token. Esa es la línea entre los dos fallos: `401` significa que el token no es confiable, `403` significa que lo es y el rol aún no lo tendrá. Las credenciales vuelven con el alcance de `account`, llevando los permisos propios del rol. No hay ningún campo `policy` aquí — a diferencia de `POST /v1/assume-role`, una sesión federada no puede ser reducida en el momento del intercambio, por lo que las políticas adjuntas del rol son la concesión completa. Tamaño del papel en consecuencia. Debido a que no requiere credenciales, las solicitudes están limitadas por la velocidad por IP del cliente. En qué proveedores se confía es parte de la configuración de la propia plataforma. Todavía no hay una API para registrar un proveedor de identidad propio, por lo que esta operación está activa pero no tiene un proveedor externo cuyos tokens aceptaría; los roles que la usan hoy en día son administrados por la plataforma. operationId: assumeRoleWithWebIdentity requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssumeRoleWithWebIdentityRequest' responses: '200': description: Función asumida con éxito content: application/json: schema: $ref: '#/components/schemas/AssumeRoleResponse' '400': $ref: '#/components/responses/BadRequest' '401': description: > El token no se verificó: un firmante no confiable, un público que esta plataforma no acepta o un token caducado. Un mensaje cubre los tres. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: invalid web identity token request_id: 550e8400-e29b-41d4-a716-446655440000 '403': description: > El token se verificó, pero la directiva de confianza del rol no lo admite: el proveedor no está entre sus `principals` o una condición de las declaraciones del token no se cumplió. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IAM_CANNOT_ASSUME_ROLE message: You are not authorized to assume this role request_id: 550e8400-e29b-41d4-a716-446655440000 '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '501': description: > La federación de identidades web no está configurada en esta región, por lo que no hay ningún proveedor para verificar un token. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_IMPLEMENTED message: web identity federation is not configured request_id: 550e8400-e29b-41d4-a716-446655440000 '503': description: > La credencial no se rechazó: una dependencia de la plataforma no pudo completar el intercambio. Vuelva a intentarlo en lugar de rotar el rol o la clave. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: SERVICE_UNAVAILABLE message: >- The service is temporarily unavailable. Please try again later. request_id: 550e8400-e29b-41d4-a716-446655440000 security: [] components: schemas: AssumeRoleWithWebIdentityRequest: type: object additionalProperties: false description: > El intercambio que envía un llamador federado. No lleva firma — el token es la credencial — por lo que cada campo se lee desde el cuerpo y nada se infiere del contexto de la solicitud. required: - web_identity_token - role - account properties: web_identity_token: type: string description: > El token de identidad a intercambiar, como un JWT firmado. Se verifica antes de que se lea cualquier rol: la firma debe encadenar a una clave que el proveedor de confianza publica, la audiencia debe ser la que esta plataforma fue configurada para aceptar, y `exp` debe estar en el futuro. example: eyJhbGciOiJSUzI1NiIsImtpZCI6... role: $ref: '#/components/schemas/RoleReference' account: $ref: '#/components/schemas/AccountReference' session_name: type: string description: > Una etiqueta registrada en la sesión y en el seguimiento de auditoría. Por defecto, se establece en la afirmación `sub` del token, por lo que una sesión sin nombre todavía registra de qué identidad proviene. example: reports-exporter duration_seconds: type: integer minimum: 900 maximum: 43200 default: 3600 description: > Duración de validez de la credencial (15 min a 12 horas). Un valor por encima de la propia `max_session_duration` del rol es rechazado en lugar de ser sujetado. example: 3600 AssumeRoleResponse: type: object description: > Las credenciales de una sesión de rol, en ambas formas que se pueden presentar. `access_token` es un token portador para esta API — envíelo como `Authorization: Bearer `. Los otros cuatro campos son credenciales de AWS SigV4 para el punto final de almacenamiento de objetos compatible con S3, que no dice nada más. Ambos provienen de la misma sesión y comparten su vencimiento, por lo que revocar la sesión detiene a ambos a la vez. Utilice cualquiera que sea el punto final que está llamando; no hay necesidad de elegir uno en el momento de la solicitud. properties: access_token: type: string description: > Token portador para la API de Basaltic. Presencia en cada sesión de rol. example: eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9... token_type: type: string description: Siempre `Bearer` cuando `access_token` está presente. example: Bearer expires_in: type: integer description: Segundos hasta que `access_token` expira. example: 3600 access_key_id: type: string description: Id de clave de acceso SigV4, para el punto final S3. example: AKIA... secret_access_key: type: string description: Secreto SigV4, para el punto final S3. example: wJalrXUtnFEMI... session_token: type: string description: > Token de sesión SigV4, para el punto final S3. Enviar como `X-Amz-Security-Token` e incluirlo en `SignedHeaders`. example: FwoGZXIvYXdzE... expiration: type: string format: date-time description: > Cuando la sesión —y por lo tanto ambos formularios de credenciales— caduca. example: '2026-01-15T09:30:00Z' account_id: type: string description: UUID de la cuenta propietaria del rol de destino. format: uuid account_handle: type: string description: Identificador de cuenta de propietario del rol de destino. role_id: type: string description: UUID inmutable del rol asumido. format: uuid Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de error que identifica el tipo de error example: INVALID_INPUT message: type: string description: Mensaje de error legible por el ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores no sensibles opcionales para la interpolación de errores localizados, codificados por código de error. Nunca presente por errores del servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuración example: 550e8400-e29b-41d4-a716-446655440000 RoleReference: type: string description: >- UUID del rol de la cuenta, nombre inmutable en la cuenta seleccionada, o crn:iam:::función/. AssumeRole puede usar un CRN calificado para dirigirse a otra cuenta de la misma organización, y la sesión resultante se vincula a la cuenta de rol de destino. example: crn:iam::production:role/reports AccountReference: type: string description: >- UUID de la cuenta, identificador inmutable o CRN de una cuenta de espacio de trabajo (crn:workspace:::account/La cuenta establece la organización propietaria para la federación y debe coincidir con la cuenta de rol de destino. example: crn:workspace:::account/9f8b1c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d responses: BadRequest: description: Parámetros de solicitud no válidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: No se encontró el recurso content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 TooManyRequests: description: > Límite de velocidad excedido. El presupuesto es una ventana fija contada por punto final y por llamador (el principal autenticado cuando la solicitud lleva credenciales, la IP del cliente de lo contrario), de modo que un punto final con restricción nunca gasta el presupuesto de otro, y un inquilino nunca gasta el de otro. Espere `Retry-After` segundos, luego vuelva a intentarlo. Los encabezados `X-RateLimit-*` también se basan en las respuestas exitosas de un punto final con límite de velocidad, por lo que un cliente puede acelerarse en lugar de descubrir el límite al alcanzarlo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Too many requests, please try again later request_id: 550e8400-e29b-41d4-a716-446655440000 headers: Retry-After: description: Segundos para esperar antes de volver a intentarlo. Nunca a cero. required: true schema: type: integer minimum: 1 example: 42 X-RateLimit-Limit: description: Solicitudes permitidas por ventana en este punto final. required: true schema: type: integer minimum: 1 example: 5 X-RateLimit-Remaining: description: Solicitudes que quedan en la ventana actual. Siempre 0 en un 429. required: true schema: type: integer minimum: 0 example: 0 X-RateLimit-Reset: description: >- Segundos hasta que la ventana se reinicia: una duración, no una marca de tiempo, por lo que no necesita ningún acuerdo de reloj entre el cliente y el servidor. required: true schema: type: integer minimum: 1 example: 42 InternalServerError: description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer `. Esta es la forma recomendada de autenticación. Obtén el token intercambiando el par de claves de acceso de una cuenta de servicio en `POST /v1/oauth/token` con `grant_type=client_credentials`. Es el flujo estándar de credenciales de cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar el token por ti. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Los tokens duran una hora por defecto. El mismo par de claves de acceso también sirve como credencial AWS SigV4 para el endpoint de objetos compatible con S3, que solo acepta ese método de autenticación. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.