Autenticação e tokens de API
Como um programa se autentica na API. Explica a diferença entre a sessão do painel e um token de API, e como limitar um token ao mínimo de que ele precisa.
Sessão ou token?
| Sessão do painel | Token de API | |
|---|---|---|
| Quem a usa | uma pessoa, num browser | um programa |
| Dura | minutos, e renova-se | meses |
| Onde vive | cookie | no teu CI, num ficheiro de configuração |
| Âmbito | tudo o que a pessoa pode | o subconjunto que escolheste |
Se estás a escrever um script, é token. Não uses as credenciais de uma pessoa num programa: quando essa pessoa sair, o programa para — e, pior, tudo o que o programa fez fica registado no nome dela.
Criar um token
Em Desenvolvedor → Tokens de API:
- Dás-lhe um nome que diga para que é.
deploy-cidiz;token1não. - Escolhes as permissões.
- Opcionalmente, limitas a sites concretos.
- Escolhes quanto tempo dura.
O segredo aparece uma vez. Não voltamos a mostrá-lo — guardamos apenas uma impressão dele, o que significa que não o podemos ler nem recuperar. Se o perderes, rodas o token.
Usar
curl -H "Authorization: Bearer ffpat_..." \
https://api.fortfox.pt/v1/sites
O prefixo ffpat_ identifica a credencial como token de API — é o que nos deixa distinguir um token de uma sessão sem tentar descodificar as duas coisas.
Permissões
Um token nunca pode mais do que a pessoa que o criou. O que ele pode é a interseção de três coisas:
- O que a pessoa pode.
- O que escolheste ao criar o token.
- O que é permitido a tokens de todo.
O terceiro ponto é o que impede um token de fazer o que só uma pessoa deve fazer. Mudar a palavra-passe, gerir a equipa, mexer na faturação e emitir tokens novos são coisas que nenhum token pode, por muito que o dono da conta as possa: uma credencial de automação que possa criar mais credenciais é uma escada.
O painel só te oferece as permissões que um token pode levar.
Escolher o mínimo
Um token para um deploy que só limpa a cache precisa disso e mais nada. A pergunta a fazer é «se este token aparecer num repositório público, o que é que a pessoa que o encontrar consegue fazer?» — e a resposta deve ser aborrecida.
Limitar a sites
Um token pode ficar preso a uma lista de sites. Fora dessa lista, qualquer pedido a um site responde como se ele não existisse.
É o que serve para um cliente ou um integrador: dás-lhe um token do site dele, e o resto da conta não existe para aquele token.
Duas notas:
- A criação de sites não é limitável por site — um site que ainda não existe não pode estar numa lista. Se um token limitado não deve poder criar sites, não lhe dês a permissão de criação.
- Um token não alcança sites partilhados contigo. Uma partilha é dada a uma pessoa, e um token é uma credencial da conta de quem o emitiu. Ver partilhar com clientes.
Validade e rotação
Um token tem prazo. A expiração não é um incómodo: é a garantia de que uma credencial esquecida num servidor antigo deixa de valer sozinha.
Rodar gera um segredo novo e mantém o resto — nome, permissões, âmbito. É o que se faz quando um token pode ter vazado, e é uma boa prática fazê-lo periodicamente mesmo sem suspeitas.
Revogar mata o token de imediato.
Limites
Há um número máximo de tokens activos por pessoa. Os revogados e os expirados não contam — é um tecto ao que está vivo, e existe para que uma conta não acumule dezenas de credenciais que ninguém sabe onde estão.
Se um segredo vazar
- Revoga o token, primeiro. Antes de investigar.
- Cria outro, com o âmbito mínimo, e actualiza quem o usava.
- Vê o registo de atividade da conta, à procura do que foi feito com ele.
Revogar é instantâneo e não parte nada que não estivesse já em risco.