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

# Obter token de identidade web

> Emita uma prova de identidade vinculada a uma audiência usando uma sessão autenticada de service account
ou de role assumida. A conta selecionada deve corresponder à conta da sessão.
Usuários humanos devem primeiro assumir uma role da conta. O chamador precisa de
iam:GetWebIdentityToken no CRN de sua própria service account ou role.

O sujeito é derivado da identidade persistida, nunca de campos da requisição:
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:role:ROLE_UUID ou
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:service-account:SERVICE_ACCOUNT_UUID.
Uma sessão direta de metadados de VM preserva seu sujeito instance:INSTANCE_UUID.
Sessões encadeadas representam a role de destino. O emissor é https://iam.basaltic.sh;
a descoberta pública e o JWKS de workloads estão disponíveis nesse host.

Qualquer audiência externa permitida é aceita, não apenas AWS. As condições de política
basalt:IdentityTokenAudience e basalt:IdentityTokenDurationSeconds restringem
a emissão. Tokens duram no máximo cinco minutos e usam chaves separadas das dos tokens da API.
As respostas não são armazenadas em cache nem para repetição por idempotência. Revogar a sessão
de origem impede novas emissões; provas já emitidas continuam válidas até expirarem.


> [!NOTE]
>
> Requer a ação IAM **`iam:GetWebIdentityToken`**. Consulte [Permissões IAM](https://docs.basaltic.sh/iam/permissions.md) para a lista completa, o que cada ação abrange e um exemplo de política.


## OpenAPI

````yaml /pt/api-reference/specs/iam.yaml post /v1/get-web-identity-token
openapi: 3.0.3
info:
  title: API do Basaltic IAM
  version: 1.0.0
  description: >
    Gerenciamento de identidade e acesso de conta: contas de serviço, funções,
    políticas de conta e sessões temporárias com escopo de conta. A autenticação
    e o login pessoal permanecem no IAM. Organizações, contas, usuários, grupos
    e políticas da organização são gerenciados pela API do Workspace.


    As funções e políticas personalizadas pertencem à conta selecionada.Seus
    CRNs globais usam uma região vazia e o identificador da conta proprietária.
    Políticas de sistema compartilhadas usam crn:iam:::policy/<name>As entradas
    de relacionamento são classificadas uma vez como CRN, UUID ou nome, sem
    fallback de sintaxe.


    AssumeRole resolve a conta de propriedade da função de destino. O chamador
    precisa de permissão de origem e a função de destino deve confiar no
    chamador; a sessão resultante usa somente as permissões da função de
    destino, sujeita a limites e restrições de sessão.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://iam.basaltic.sh
    description: Endpoint global da API
security:
  - BearerAuth: []
paths:
  /v1/get-web-identity-token:
    post:
      tags:
        - IAM
      summary: Obter token de identidade web
      description: >
        Emita uma prova de identidade vinculada a uma audiência usando uma
        sessão autenticada de service account

        ou de role assumida. A conta selecionada deve corresponder à conta da
        sessão.

        Usuários humanos devem primeiro assumir uma role da conta. O chamador
        precisa de

        iam:GetWebIdentityToken no CRN de sua própria service account ou role.


        O sujeito é derivado da identidade persistida, nunca de campos da
        requisição:

        org:ORGANIZATION_UUID:account:ACCOUNT_UUID:role:ROLE_UUID ou

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

        Uma sessão direta de metadados de VM preserva seu sujeito
        instance:INSTANCE_UUID.

        Sessões encadeadas representam a role de destino. O emissor é
        https://iam.basaltic.sh;

        a descoberta pública e o JWKS de workloads estão disponíveis nesse host.


        Qualquer audiência externa permitida é aceita, não apenas AWS. As
        condições de política

        basalt:IdentityTokenAudience e basalt:IdentityTokenDurationSeconds
        restringem

        a emissão. Tokens duram no máximo cinco minutos e usam chaves separadas
        das dos tokens da API.

        As respostas não são armazenadas em cache nem para repetição por
        idempotência. Revogar a sessão

        de origem impede novas emissões; provas já emitidas continuam válidas
        até expirarem.
      operationId: getWebIdentityToken
      parameters:
        - name: X-Account-Id
          in: header
          required: false
          description: >-
            UUID, CRN ou identificador da conta proprietária. Por padrão, usa a
            conta do workload autenticado.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetWebIdentityTokenRequest'
      responses:
        '200':
          description: Prova de identidade 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: >-
            Audiência esperada pelo serviço externo. Espaços, caracteres de
            controle e a audiência reservada da API Basaltic `basaltic` são
            rejeitados. Condições de permissão podem restringir a audiência
            aceita.
          example: sts.amazonaws.com
        duration_seconds:
          type: integer
          minimum: 60
          maximum: 300
          default: 300
          description: >-
            Duração da prova de identidade. Omita para usar 300 segundos. A
            sessão autenticada deve permanecer válida pelo período solicitado.
    GetWebIdentityTokenResponse:
      type: object
      required:
        - token
        - expires_at
      properties:
        token:
          type: string
          description: >-
            JWT assinado com ES256 para a audiência solicitada. Essa prova é uma
            credencial; não a registre em logs. Ela não autentica nas APIs
            Basaltic.
        expires_at:
          type: string
          format: date-time
          description: Expiração da prova de identidade.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Código de erro identificando o tipo de erro
              example: INVALID_INPUT
            message:
              type: string
              description: Mensagem de erro legível pelo ser humano
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Valores não sensíveis opcionais para interpolação de erros
                localizados, codificados por código de erro. Nunca presente para
                erros de servidor.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Solicitar ID para depuração
              example: 550e8400-e29b-41d4-a716-446655440000
  responses:
    BadRequest:
      description: Parâmetros de solicitação invá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: Autenticação necessária ou token invá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: Permissões 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: >
        Limite de taxa excedido. O orçamento é uma janela fixa contada por
        endpoint e por chamador — o principal autenticado quando a solicitação
        carrega credenciais, o IP do cliente caso contrário — para que um
        endpoint limitado nunca gaste o orçamento de outro e um locatário nunca
        gaste o de outro.


        Aguarde `Retry-After` segundos, em seguida, tente novamente. Os
        cabeçalhos `X-RateLimit-*` também são baseados nas respostas
        bem-sucedidas de um endpoint com taxa limitada, para que um cliente
        possa se adaptar ao invés de descobrir o limite ao atingi-lo.
      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 aguardar antes de tentar novamente. Nunca zero.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 42
        X-RateLimit-Limit:
          description: Solicitações permitidas por janela neste endpoint.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 5
        X-RateLimit-Remaining:
          description: Solicitações deixadas na janela atual. Sempre 0 em um 429.
          required: true
          schema:
            type: integer
            minimum: 0
          example: 0
        X-RateLimit-Reset:
          description: >-
            Segundos até que a janela seja redefinida — uma duração, não um
            carimbo de data/hora, portanto, não precisa de acordo de clock entre
            cliente e servidor.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 42
    InternalServerError:
      description: Erro interno do 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: Serviço temporariamente indisponível
      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 tentar novamente
          schema:
            type: integer
          example: 300
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >+
        Um token bearer OAuth 2.0, enviado como `Authorization: Bearer <token>`.
        Esta é a forma recomendada de autenticação.


        Obtenha o token trocando o par de chaves de acesso de uma conta de
        serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
        Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
        com OAuth podem obter e renovar o token para você.


        ```

        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```


        Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
        também serve como credencial AWS SigV4 para o endpoint de objetos
        compatível com S3, que aceita somente esse método de autenticação.


````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.