> ## 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. # Autenticação > Como uma solicitação prova quem é: um token de portador da sua chave de acesso. Cada solicitação à API Basaltic inclui um **token bearer**. Há duas formas de obtê-lo, dependendo de quem faz a chamada. Um **programa** autentica como uma conta de serviço: ele mantém um par de chaves de acesso e o troca por um token de curta duração. Uma **pessoa** faz login com o `basaltic login`, que abre um navegador e retorna um token que age como ela. Ambos usam `Authorization: Bearer`. O acesso pessoal à organização e o acesso de função de conta são separados: todos os seres humanos assumem uma função de conta atribuída antes de fazer solicitações de serviço de conta. A diferença não é cosmética. Uma conta de serviço não pode criar uma organização, aceitar um convite ou alterar a organização — isso requer uma pessoa. Se a CLI está dizendo que uma operação requer um usuário, é isso que ela significa. O mesmo par de chaves também é sua credencial do AWS Signature Version 4 para o endpoint de objeto compatível com o S3, o que não diz mais nada. Uma credencial, duas apresentações e nenhuma escolha a ser feita no momento da solicitação: token para esta API, par de chaves para o S3. ## Como obter credenciais As chaves de acesso pertencem a uma **conta de serviço**, nunca a uma pessoa. Crie um, dê uma política e, em seguida, crie uma credencial nele — veja o [quickstart](/pt/quickstart#issue-api-credentials). O segredo é mostrado uma vez, na criação, e nunca mais. Para credenciais de curta duração, consulte [credenciais temporárias para uma função](#temporary-credentials-for-a-role) abaixo. ## Como obter um token ```bash theme={null} curl -s -u "$ACCESS_KEY_ID:$SECRET_ACCESS_KEY" \ -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` ```json theme={null} { "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...", "token_type": "Bearer", "expires_in": 3600 } ``` Este é o OAuth 2.0 credencial de cliente de concessão, não modificado, então qualquer biblioteca OAuth-aware irá executá-lo e atualizar para você. As credenciais podem ir em um cabeçalho HTTP Basic, como acima, ou como campos de formulário `client_id` e `client_secret`. Então envie-o em cada chamada: ``` Authorization: Bearer X-Account-Id: ``` Um token de conta de serviço está vinculado à conta proprietária. O cabeçalho deve concordar com essa conta para operações de conta. Não pode mover o token para uma conta diferente. Para isso, assuma uma função confiável na conta de destino. As APIs de organização avaliam as concessões de organização explícitas da identidade. ### Validade do token Uma hora por padrão. Peça outro com `duration_seconds`, entre 900 e 43200. Um valor fora desse intervalo é fixado nele em vez de ser recusado, então pedir um dia dá o token mais longo permitido. Trate o token como opaco. Não analise e não use a string de token como uma chave em um cache, uma lista de negação ou uma tabela de deduplicação — uma assinatura tem várias codificações válidas, então um token pode aparecer como várias strings diferentes. ### Quando uma solicitação é recusada Duas respostas são semelhantes e têm remédios opostos: | `error` | O que significa | O que fazer | | - | - | - | | `invalid_client` | A chave de acesso foi rejeitada — desconhecida, segredo errado, desativada ou expirada | Verificar ou rodar a credencial | | `invalid_grant` | A chave está bem; a organização está suspensa ou ainda está sendo integrada | Corrigir a organização. Girar a chave não vai ajudar | Uma chave de acesso desconhecida e uma resposta secreta incorreta de forma idêntica, de modo que o endpoint não pode ser usado para descobrir quais chaves existem. Os erros aqui usam a forma OAuth 2.0 — `{"error": ..., "error_description": ...}` — ao invés do envelope usual desta API, porque é isso que as bibliotecas cliente OAuth analisam. ### Como revogar um token ```bash theme={null} curl -s -X POST -H "Authorization: Bearer $TOKEN" \ -d "token=$TOKEN" https://iam.basaltic.sh/v1/oauth/revoke ``` Isso encerra a sessão por trás do token, então tudo o que ele emitiu pára de funcionar na próxima solicitação, em vez de na expiração. Ele responde `200` se alguma coisa foi revogada ou não — um endpoint que lhe dissesse a diferença diria a qualquer um que tivesse um token se ele ainda funciona. ## Como entrar com sua identidade pessoal ```bash theme={null} basaltic login ``` Ele imprime um URL. Abra-o, aprove a CLI, escolha uma organização e a página lhe dará um código; cole-o de volta no terminal e você estará conectado. Nenhuma credencial de longa duração é criada — a CLI mantém um token de curta duração e um token de atualização em `~/.config/basaltic/credentials.yaml`, modo 0600, separado de `config.yaml` para que sua configuração permaneça segura para compartilhamento. **O navegador não precisa estar na mesma máquina.** É por isso que é um código e não um redirecionamento: abra a URL no seu laptop, leve o código para o terminal no servidor em que você está trabalhando, um redirecionamento teria que aterrissar em algum lugar, e "algum lugar" é sempre apenas a máquina que executa o navegador. Use isso quando você é uma pessoa em um terminal. Use uma tecla de acesso quando o chamador for um programa que precisa ser executado sem você. Sob o capô é um código de autorização OAuth 2.0 com PKCE, entregue fora de banda (`redirect_uri=urn:ietf:wg:oauth:2.0:oob`). Algumas consequências que vale a pena conhecer: * **A CLI não mantém segredo de cliente.** Ele é enviado para laptops, então qualquer segredo que ele tivesse seria legível por qualquer pessoa que tivesse o binário. O que protege o fluxo é o PKCE: resgatar o código requer um verificador que gera a CLI quando o fluxo começa e não envia até o momento em que gasta o código. * **O código é de uso único e dura cinco minutos.** É gasto pela tentativa, não pelo sucesso, então um código interceptado não pode ser re-tentado contra verificadores adivinhados. * **Cole-o apenas no terminal que você iniciou.** Um código não vale nada sem o verificador mantido pelo processo que o pediu, então colar um em algum outro programa não faz nada — mas um programa que pede para você não está fazendo nada que precise de você. Sua sessão dura o mesmo tempo que uma sessão de console. A CLI atualiza-a em segundo plano; o `basaltic auth status` mostra quem você é, em que organização você está e quando a credencial expira. `basaltic auth logout` revoga-o. Máquinas não monitoradas — um executor CI, um trabalho cron — devem usar uma chave de acesso de conta de serviço em vez desse fluxo. Ele precisa de uma pessoa para aprová-lo, e um token que age como uma pessoa é a coisa errada para o trabalho autônomo de qualquer maneira. ## Credenciais temporárias para uma função `POST /v1/assume-role` em `iam.basaltic.sh` emite credenciais para uma função em sua organização. A suposição de contas cruzadas precisa de uma permissão de origem `iam:AssumeRole` e de uma confiança de destino. As atribuições de função de conta humana fornecem a permissão de origem; elas não alteram a política de confiança. A resposta carrega **ambos** os formulários de uma sessão: um `access_token` para esta API e os quatro SigV4 para o S3. Eles compartilham um prazo de validade, e revogar a sessão interrompe ambos. As instâncias obtêm o mesmo par do serviço de metadados: o caminho compatível com a AWS para credenciais do S3 e `/latest/basaltic/iam/access-token` para o token. A resposta também inclui `account_id`, `account_handle`, e `role_id`. Verifique estes contra o alvo que você selecionou. Uma sessão usa as permissões da função de destino, sem unir permissões de sua origem. O console mantém um token pessoal para páginas de espaço de trabalho e um token de função de conta selecionado separado. As integrações devem preservar a mesma distinção. Veja [account access](/pt/workspace/accounts) e [roles](/pt/iam/roles#assuming-a-role). ## Solicitação de assinatura (retirada) APIs de plano de controle aceitam tokens de portador. Assinaturas de solicitação `BASALTIC-HMAC-SHA256` legadas não são aceitas. Troque credenciais de conta de serviço através de `/v1/oauth/token`, ou use o `access_token` de uma resposta AssumeRole. O endpoint de objeto compatível com o S3 usa o padrão AWS Signature Versão 4. Ao usar credenciais temporárias, forneça o token de sessão por meio da opção de token de sessão do AWS SDK. As solicitações de plano de controle não usam assinatura S3. ## Limites de taxa Não há orçamento global de solicitação. Um limite se aplica somente quando uma operação documenta um `429`, e cada um desses pontos finais conta sua própria janela fixa. Tudo o resto é limitado por cota em vez de taxa de solicitação. Os endpoints limitados aqui são os dois públicos, não autenticados — `GET /v1/regions` e o catálogo de preços `GET /v1/prices` — que são contados por IP do cliente porque não há principal para contar. Respostas - `429` e `2xx` igualmente - carregam `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` para que você possa se acalmar em vez de descobrir o teto batendo nele. Leia `X-RateLimit-Limit` em vez de codificar um número. Em um `429`, honra `Retry-After`. Retentar mais cedo é recusado e estende a janela, porque a tentativa recusada é contada. Alguns recursos medem o trabalho em vez da solicitação — o envio de uma mensagem é limitado por identidade por segundo — e documentam seu próprio `429` na operação. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.