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. 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 abaixo.Como obter um token
client_id e client_secret.
Então envie-o em cada chamada:
Validade do token
Uma hora por padrão. Peça outro comduration_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:
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
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
~/.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ê.
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 e roles.
Solicitação de assinatura (retirada)
APIs de plano de controle aceitam tokens de portador. Assinaturas de solicitaçãoBASALTIC-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 um429, 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.