> ## 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. # Troque uma chave de acesso por um token de portador > Troque o par de chaves de acesso de uma conta de serviço por um token de portador de curta duração e, em seguida, envie esse token como `Authorization: Bearer ` em cada outra chamada. Esta é a forma normal de autenticação. O par de chaves de acesso permanece a única credencial de longa duração que uma conta de serviço tem; o que muda é que você apresenta um token derivado dele em vez de assinar cada solicitação. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` O mesmo par de chaves é *também* a credencial AWS SigV4 para o endpoint de objeto compatível com o S3, o que não diz mais nada. Use o token para essa API e o par de chaves para o S3; não há necessidade de escolher. **Os erros aqui usam a forma OAuth 2.0, não o envelope usual desta API** — `{"error": "...", "error_description": "..."}` — porque cada biblioteca cliente OAuth analisa isso e nada mais. Duas respostas importam e seus remédios são opostos. `invalid_client` significa que a chave foi rejeitada: verifique ou gire-a. `invalid_grant` significa que a chave está bem e a organização está suspensa ou ainda está sendo integrada, onde a rotação de uma chave de trabalho desperdiçaria seu tempo. Uma chave de acesso desconhecida e um segredo errado respondem a `invalid_client` com a mesma mensagem, então o endpoint não pode ser usado para descobrir quais chaves existem. Requer **nenhuma ação do IAM**. O acesso é decidido pelas próprias regras do endpoint, e não por uma política — consulte a descrição acima. ## OpenAPI ````yaml /pt/api-reference/specs/iam.yaml post /v1/oauth/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/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/oauth/token: post: tags: - IAM summary: Troque uma chave de acesso por um token de portador description: > Troque o par de chaves de acesso de uma conta de serviço por um token de portador de curta duração e, em seguida, envie esse token como `Authorization: Bearer ` em cada outra chamada. Esta é a forma normal de autenticação. O par de chaves de acesso permanece a única credencial de longa duração que uma conta de serviço tem; o que muda é que você apresenta um token derivado dele em vez de assinar cada solicitação. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` O mesmo par de chaves é *também* a credencial AWS SigV4 para o endpoint de objeto compatível com o S3, o que não diz mais nada. Use o token para essa API e o par de chaves para o S3; não há necessidade de escolher. **Os erros aqui usam a forma OAuth 2.0, não o envelope usual desta API** — `{"error": "...", "error_description": "..."}` — porque cada biblioteca cliente OAuth analisa isso e nada mais. Duas respostas importam e seus remédios são opostos. `invalid_client` significa que a chave foi rejeitada: verifique ou gire-a. `invalid_grant` significa que a chave está bem e a organização está suspensa ou ainda está sendo integrada, onde a rotação de uma chave de trabalho desperdiçaria seu tempo. Uma chave de acesso desconhecida e um segredo errado respondem a `invalid_client` com a mesma mensagem, então o endpoint não pode ser usado para descobrir quais chaves existem. operationId: getOAuthToken requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OAuthTokenRequest' application/json: schema: $ref: '#/components/schemas/OAuthTokenRequest' responses: '200': description: Um token de portador content: application/json: schema: $ref: '#/components/schemas/OAuthTokenResponse' '400': description: > Solicitação mal formada ou um tipo de concessão que esta implantação não atende. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: unsupported_grant_type error_description: unsupported grant type '401': description: > A autenticação do cliente falhou — uma chave de acesso desconhecida, um segredo errado ou uma chave desativada ou expirada. Uma resposta cobre todos eles. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: invalid_client error_description: client authentication failed '403': description: > A credencial é válida, mas a organização não está ativa. Nada está errado com a chave. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: invalid_grant error_description: Organization is suspended '429': $ref: '#/components/responses/TooManyRequests' '503': description: > A troca não pôde ser concluída. A credencial não foi recusada — tente novamente em vez de girá-la. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: temporarily_unavailable error_description: try again shortly security: [] components: schemas: OAuthTokenRequest: type: object description: > Uma solicitação de token OAuth 2.0. O codificado em formulário é o que a RFC 6749 especifica e o que as bibliotecas cliente enviam; JSON também é aceito. As credenciais do cliente podem ser enviadas como HTTP Basic (`Authorization: Basic base64(key_id:secret)`, que é o que a maioria das bibliotecas faz por padrão) ou como campos `client_id` e `client_secret`. Basic ganha se ambos estiverem presentes. required: - grant_type properties: grant_type: type: string enum: - client_credentials - authorization_code - refresh_token description: > `client_credentials` é o que se usa para uma conta de serviço: ele troca um par de chaves de acesso por um token, e não precisa de mais nada. `authorization_code` e `refresh_token` pertencem ao login interativo que uma pessoa executa (`basaltic login`), onde o token nomeia um USER ao invés de uma conta de serviço. Eles são conduzidos pela CLI, não escritos à mão. Verifique o documento de metadados do servidor de autorização antes de ramificar neles — eles são anunciados somente onde um endpoint de autorização está configurado. example: client_credentials client_id: type: string description: O id da chave de acesso. Omita ao usar HTTP Basic. example: BYCLD1a2b3c4d5e6f7 client_secret: type: string format: password description: A chave de acesso secreta. Omita ao usar HTTP Basic. duration_seconds: type: integer minimum: 900 maximum: 43200 description: > Tempo de vida do token solicitado. Uma extensão Basaltic, não um parâmetro OAuth — omita-o e você obtém o padrão. Valores fora do intervalo são fixados nele em vez de serem recusados, então pedir um dia produz o token mais longo permitido. example: 3600 code: type: string description: > O código de autorização do redirecionamento de consentimento. Uso único, e válido por cinco minutos. `authorization_code` concede apenas. code_verifier: type: string description: > O verificador PKCE cujo SHA-256 foi enviado como `code_challenge` quando o fluxo começou (RFC 7636). Requerido com `authorization_code`: é o que prova que este é o cliente que iniciou o fluxo, uma vez que uma CLI não mantém nenhum segredo de cliente. redirect_uri: type: string description: > O mesmo `redirect_uri` para o qual o código foi emitido — para a CLI, `urn:ietf:wg:oauth:2.0:oob`. Re-checado aqui, para que um código não possa ser resgatado sob um diferente (RFC 6749 4.1.3). example: urn:ietf:wg:oauth:2.0:oob refresh_token: type: string description: > `refresh_token` concede apenas. Renova uma sessão de usuário sem outra viagem através do navegador. Rotação a cada uso — guarde o novo. OAuthTokenResponse: type: object description: Resposta de token RFC 6749. required: - access_token - token_type - expires_in properties: access_token: type: string description: > Enviar como `Authorization: Bearer `. Opacos para os clientes: não analisem e não digitem nada na string de token. example: eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9... token_type: type: string enum: - Bearer example: Bearer expires_in: type: integer description: Segundos até que o token expire. example: 3600 refresh_token: type: string description: > Retornado apenas pelas concessões do usuário (`authorization_code` e `refresh_token`). Apresente-o ao `refresh_token` para renovar sem outra viagem de ida e volta do navegador; ele é ROTATADO em cada uso, então substitua a cópia armazenada toda vez. Uma conta de serviço não recebe nenhuma. Ele já possui uma chave de acesso de longa duração e pode simplesmente executar `client_credentials` novamente, então um token de atualização seria uma segunda credencial para armazenar sem ganho. OAuthError: type: object description: > Resposta de erro RFC 6749. Deliberadamente NÃO o envelope de erro usual desta API: as bibliotecas de cliente OAuth analisam esta forma e nada mais, e o ponto principal do endpoint de token é que um cliente de estoque pode alcançá-lo. required: - error properties: error: type: string enum: - invalid_request - invalid_client - invalid_grant - unsupported_grant_type - temporarily_unavailable - server_error description: > `invalid_client` — a chave foi rejeitada; verifique ou gire-a. `invalid_grant` — a chave está bem, a organização não está ativa. Esses dois têm remédios opostos e valem a pena distinguir antes que alguém gire uma credencial de trabalho. example: invalid_client error_description: type: string description: Detalhe legível pelo homem. Não combine nele. example: client authentication failed 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: 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 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `. 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.