Saltar para o conteúdo

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.

Avançado7 min de leitura

Sessão ou token?

Sessão do painelToken de API
Quem a usauma pessoa, num browserum programa
Duraminutos, e renova-semeses
Onde vivecookieno teu CI, num ficheiro de configuração
Âmbitotudo o que a pessoa podeo 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:

  1. Dás-lhe um nome que diga para que é. deploy-ci diz; token1 não.
  2. Escolhes as permissões.
  3. Opcionalmente, limitas a sites concretos.
  4. 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:

  1. O que a pessoa pode.
  2. O que escolheste ao criar o token.
  3. 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

  1. Revoga o token, primeiro. Antes de investigar.
  2. Cria outro, com o âmbito mínimo, e actualiza quem o usava.
  3. 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.

← Toda a documentação