Autenticação

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

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.

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 × âmbito

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 âmbitos, e vale a pena aprender a gramática uma vez:

Todos os âmbitos terminam em :read. Não há qualquer âmbito 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-images:read apenas em restaurant-1, lê as fotografias 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 âmbitos 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 âmbito 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 âmbitos, e GET /v1/restaurants/{id}/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 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 âmbitos.
2. Você 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.