# Autenticação

> Chaves de parceiro, os vinte e seis scopes, o que significa uma concessão, e como rodar sem interrupção.

Source: https://developers.backresto.com/pt/docs/authentication

Todos os pedidos à API de Parceiros levam uma credencial, no sítio habitual:

```http
Authorization: Bearer brp_<prefix>.<secret>
```

Não há outro esquema. Sem chave na query string, sem autenticação básica, sem
cookies. Um pedido sem esse cabeçalho, ou com um valor malformado, responde
`401` antes de qualquer outra coisa ser avaliada.

## O que é uma chave

Uma chave tem duas metades separadas por um ponto.

| Metade | O que é | Onde pode aparecer |
| --- | --- | --- |
| `brp_<prefix>` | Um identificador público da credencial. | Os seus registos, um email de suporte, a lista de chaves neste site. |
| `<secret>` | 256 bits de aleatoriedade. | O seu gestor de segredos, e o cabeçalho `Authorization`. |

O BackResto guarda o prefixo e um resumo criptográfico com chave do segredo.
**O segredo em si não é guardado e não pode ser recuperado**: nem por si, nem
pelo suporte, nem a partir da base de dados. Se se perder, revogue a chave e
crie outra.

## Concessões: restaurante × scope

Uma chave não é «uma conta com permissões». É uma lista de concessões
explícitas, cada uma delas um par:

Há **vinte e seis scopes**, e vale a pena aprender a gramática uma vez:

| Scope | Dá acesso a |
| --- | --- |
| `<collection>:read` | Uma das [vinte e seis coleções](https://developers.backresto.com/pt/docs/collections): `deliveries:read`, `delivery-pictures:read`, `cooling:read`, `temperature-records:read`, `traceability-labels:read` e assim por diante, um scope por coleção. |

Todos os scopes terminam em `:read`. Não há nenhum scope de parceiro que
escreva, e nenhum pode ser criado: o lado de escrita desta API pertence à
aplicação BackResto, e uma chave de parceiro é estruturalmente incapaz de ter
um.

Uma chave com `deliveries:read` em `restaurant-1` e `restaurant-2`, e
`delivery-pictures:read` apenas em `restaurant-1`, lê as fotografias das entregas
do primeiro restaurante e recebe `403` para o segundo. É uma configuração suportada, não um
engano: há integrações que querem os registos sem as imagens.

Peça aquilo que usa. Vinte e seis scopes não são um menu para assinalar de
ponta a ponta: o restaurante lê a lista antes de concordar com ela, e um pedido
de tudo demora mais a passar do que um pedido das quatro coleções que o seu
produto lê mesmo.

Três modos de falha, deliberadamente distintos:

- **`404`**: a chave não tem qualquer concessão para esse restaurante. A API
  não diz a quem não está autorizado se um restaurante existe.
- **`403`**: a chave tem uma concessão para esse restaurante, mas não o scope
  de que este endpoint precisa.
- **`401`**: entre outras coisas, uma chave que já não tem concessão nenhuma.
  Uma chave a quem foi retirada a última concessão deixa de se autenticar, em
  vez de responder vazio.

Para saber o que uma chave tem realmente, pergunte-lhe: `GET /v1/restaurants`
lista os restaurantes com os seus scopes, e
[`GET /v1/restaurants/{id}/collections`](https://developers.backresto.com/pt/docs/collections) lista as coleções
que ela abre.

## Quem pode emitir uma

Somos nós, mediante pedido, e apenas para restaurantes que tenham concordado.
Veja [Obter uma chave](https://developers.backresto.com/pt/docs/access) para saber o que enviar e o que recebe de
volta.

As concessões são definidas quando a chave é criada e só mudam com outro
pedido. Não há caminho (nem para si, nem para nós) que alargue uma chave sem
o restaurante concordar de novo.

## Expiração e revogação

Uma chave não expira por si própria, a não ser que tenha pedido uma que expire.
Mantém-se válida até ser revogada.

A revogação é imediata: o pedido seguinte com essa chave responde `401`, a
mesma resposta que uma chave desconhecida ou expirada recebe. Não pode ser
desfeita, e não precisa de o ser: uma substituição é uma chave nova, não uma
chave restaurada.

## Rodar sem interrupção

Uma integração pode ter duas chaves ativas ao mesmo tempo, por isso a rotação
não exige uma janela de manutenção. Peça-nos uma rotação e é por esta ordem que
acontece:

1. Emitimos uma segunda chave com os mesmos restaurantes e scopes.
2. Do seu lado, implanta o novo segredo e diz-nos quando estiver ativo em todo
   o lado.
3. Verificamos que a chave antiga deixou de ser usada: conseguimos ver quando
   cada chave se autenticou pela última vez, e é esse o sinal que torna o passo
   4 seguro.
4. Revogamos a antiga.

Rode com a periodicidade que escolher, e comece o pedido alguns dias antes de
querer a chave antiga fora de circulação: os passos 2 e 3 são seus e nossos e
têm de ser coordenados, e todo o objetivo da ordem acima é que nada fique morto
nem por um instante.

## Higiene

- **Guarde-a assim que chegar e apague o email.** Feito isso, o segredo existe
  em exatamente dois sítios: o seu gestor de segredos e o cabeçalho
  `Authorization`.
- **Uma chave por implantação**, não uma por empresa. Uma chave de testes
  exposta nunca deve ser um incidente de produção, e uma revogação nunca deve
  deitar abaixo mais do que aquilo que ficou exposto.
- **Nunca nos envie o segredo**: nem num pedido de suporte, nem para
  identificar uma chave. O prefixo público identifica-a sem ambiguidade e pode
  ser escrito em qualquer lado sem risco.
- **Vigie os `401` na sua própria monitorização.** Uma chave que começa a
  falhar foi revogada, e a resposta é uma conversa, não um ciclo de tentativas.