Gerar token API

Um token de API é a sua chave pessoal para o acesso programático ao ePulz.io. É útil quando quer alcançar o serviço a partir de scripts, das suas próprias ferramentas ou de um pipeline de CI/CD. Através da API pode criar e editar monitores, baixar dados de disponibilidade ou integrar os resultados das medições nos seus próprios sistemas. Este guia mostra onde gerar um token, qual o seu aspeto, onde guardá-lo em segurança e como revogá-lo.

Onde gerar um token

Os tokens estão associados a um utilizador específico - cada membro da equipa tem os seus próprios tokens com as suas próprias permissões.

• No painel, abra a secção Tokens de API (caminho /dashboard/api-tokens).
• Clique em + Novo token.
• Introduza um nome descritivo que lhe permita reconhecer o token (por exemplo Pipeline CI/CD ou Painel interno).
• O token é válido até o revogar - não tem data de expiração fixa.
• Depois de clicar em Criar, é apresentado o valor completo do token. Copie-o de imediato - por motivos de segurança não voltará a vê-lo.

Qual o aspeto do token

Cada token começa com o prefixo epulzio_ e tem no total mais de 40 caracteres. Exemplo (abreviado):

epulzio_2bF7nQ9k4Lm8XzR0pT3vYw5sH1cJ6dE...

O prefixo serve para reconhecer o token de imediato entre outras cadeias de carateres - por exemplo ao pesquisar nos logs ou ao analisar repositórios à procura de uma chave divulgada.

Como usar o token

O token é enviado no cabeçalho HTTP Authorization no formato:

Authorization: Bearer epulzio_xxxxxxxxxxxxxxxx

Exemplo de chamada no terminal:

curl -H "Authorization: Bearer epulzio_..." https://epulz.io/api/v1/monitors

Onde guardar o token em segurança

Trate o token como uma palavra-passe. Nunca o coloque em código de acesso público, na documentação ou em mensagens de chat.

• Localmente durante o desenvolvimento: numa variável de ambiente, por exemplo EPULZIO_TOKEN num ficheiro .env (que está no .gitignore).
• Em CI/CD: através dos segredos oferecidos pela sua plataforma (GitHub Actions secrets, GitLab CI variables, Bitbucket repository variables e afins).
• Em servidores: através de variáveis de ambiente do sistema ou de um gestor de segredos (HashiCorp Vault, AWS Secrets Manager).

Como revogar um token

• Na lista de tokens, localize o que pretende revogar e clique em Revogar.
• A revogação tem efeito imediato - as chamadas seguintes com este token recebem uma resposta 401 Unauthorized (token inválido).
• Um token revogado não pode ser restaurado. Se precisar dele novamente, gere um novo.

De tempos a tempos, percorra a lista de tokens ativos e remova os que já não utiliza. Menos tokens ativos significa uma superfície de ataque menor.