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

# Obtener token de identidad web

> Emite una prueba de identidad vinculada a una audiencia usando una sesión autenticada de cuenta de servicio
o de rol asumido. La cuenta seleccionada debe coincidir con la cuenta de la sesión.
Los usuarios humanos primero deben asumir un rol de la cuenta. El solicitante necesita
iam:GetWebIdentityToken sobre el CRN de su propia cuenta de servicio o rol.

El sujeto se deriva de la identidad persistida, nunca de campos de la solicitud:
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:role:ROLE_UUID o
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:service-account:SERVICE_ACCOUNT_UUID.
Una sesión directa de metadatos de VM conserva su sujeto instance:INSTANCE_UUID.
Las sesiones encadenadas representan el rol de destino. El emisor es https://iam.basaltic.sh;
el descubrimiento público y el JWKS de cargas están disponibles en ese host.

Se admite cualquier audiencia externa permitida, no solo AWS. Las condiciones de política
basalt:IdentityTokenAudience y basalt:IdentityTokenDurationSeconds restringen
la emisión. Los tokens duran como máximo cinco minutos y usan claves separadas de los tokens de la API.
Las respuestas no se almacenan en caché ni para repetición por idempotencia. Revocar la sesión
de origen impide nuevas emisiones; las pruebas ya emitidas siguen siendo válidas hasta caducar.


> [!NOTE]
>
> Requiere la acción IAM **`iam:GetWebIdentityToken`**. Consulta [Permisos IAM](https://docs.basaltic.sh/iam/permissions.md) para ver la lista completa, qué cubre cada acción y un ejemplo de política.


## OpenAPI

````yaml /es/api-reference/specs/iam.yaml post /v1/get-web-identity-token
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.<name>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/get-web-identity-token:
    post:
      tags:
        - IAM
      summary: Obtener token de identidad web
      description: >
        Emite una prueba de identidad vinculada a una audiencia usando una
        sesión autenticada de cuenta de servicio

        o de rol asumido. La cuenta seleccionada debe coincidir con la cuenta de
        la sesión.

        Los usuarios humanos primero deben asumir un rol de la cuenta. El
        solicitante necesita

        iam:GetWebIdentityToken sobre el CRN de su propia cuenta de servicio o
        rol.


        El sujeto se deriva de la identidad persistida, nunca de campos de la
        solicitud:

        org:ORGANIZATION_UUID:account:ACCOUNT_UUID:role:ROLE_UUID o

        org:ORGANIZATION_UUID:account:ACCOUNT_UUID:service-account:SERVICE_ACCOUNT_UUID.

        Una sesión directa de metadatos de VM conserva su sujeto
        instance:INSTANCE_UUID.

        Las sesiones encadenadas representan el rol de destino. El emisor es
        https://iam.basaltic.sh;

        el descubrimiento público y el JWKS de cargas están disponibles en ese
        host.


        Se admite cualquier audiencia externa permitida, no solo AWS. Las
        condiciones de política

        basalt:IdentityTokenAudience y basalt:IdentityTokenDurationSeconds
        restringen

        la emisión. Los tokens duran como máximo cinco minutos y usan claves
        separadas de los tokens de la API.

        Las respuestas no se almacenan en caché ni para repetición por
        idempotencia. Revocar la sesión

        de origen impide nuevas emisiones; las pruebas ya emitidas siguen siendo
        válidas hasta caducar.
      operationId: getWebIdentityToken
      parameters:
        - name: X-Account-Id
          in: header
          required: false
          description: >-
            UUID, CRN o identificador de la cuenta propietaria. Por defecto, usa
            la cuenta de la carga autenticada.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetWebIdentityTokenRequest'
      responses:
        '200':
          description: Prueba de identidad externa emitida
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                  - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWebIdentityTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    GetWebIdentityTokenRequest:
      type: object
      additionalProperties: false
      required:
        - audience
      properties:
        audience:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            Audiencia esperada por el servicio externo. Se rechazan espacios,
            caracteres de control y la audiencia reservada de la API Basaltic
            `basaltic`. Las condiciones de permisos pueden restringir la
            audiencia admitida.
          example: sts.amazonaws.com
        duration_seconds:
          type: integer
          minimum: 60
          maximum: 300
          default: 300
          description: >-
            Duración de la prueba de identidad. Omite para usar 300 segundos. La
            sesión autenticada debe seguir siendo válida durante el período
            solicitado.
    GetWebIdentityTokenResponse:
      type: object
      required:
        - token
        - expires_at
      properties:
        token:
          type: string
          description: >-
            JWT firmado con ES256 para la audiencia solicitada. Esta prueba es
            una credencial; no la registres en logs. No permite autenticarse en
            las APIs Basaltic.
        expires_at:
          type: string
          format: date-time
          description: Caducidad de la prueba de identidad.
    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
  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
    Unauthorized:
      description: Se requiere autenticación o el token no es válido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Permisos insuficientes
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              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
    ServiceUnavailable:
      description: Servicio temporalmente no disponible
      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
      headers:
        Retry-After:
          description: Segundos de espera antes de reintentar
          schema:
            type: integer
          example: 300
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >+
        Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer
        <token>`. 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.