Autenticazione

Ogni richiesta all'API Partner porta una sola credenziale, nel posto standard:

Authorization: Bearer brp_<prefix>.<secret>

Non esiste nessun altro schema. Nessuna chiave nella query string, nessuna basic auth, nessun cookie. Una richiesta priva di quell'header, o con un valore malformato, risponde 401 prima che qualsiasi altra cosa venga valutata.

Che cos'è una chiave

Una chiave ha due metà separate da un punto.

BackResto conserva il prefisso e un digest con chiave del secret. Il secret stesso non viene conservato e non può essere recuperato — né da lei, né dal supporto, né dal database. Se va perso, revochi la chiave e ne crei un'altra.

Concessioni: ristorante × ambito

Una chiave non è «un account con dei permessi». È un elenco di concessioni esplicite, ognuna una coppia:

Ci sono ventisei ambiti, e la grammatica vale la pena impararla una volta:

Ogni ambito termina con :read. Non esiste alcun ambito partner che scriva, e nessuno può essere creato: il lato in scrittura di questa API appartiene all'app BackResto, e una chiave partner è strutturalmente incapace di possederne uno.

Una chiave a cui sono stati concessi deliveries:read su restaurant-1 e restaurant-2, e delivery-images:read solo su restaurant-1, legge le fotografie del primo ristorante e riceve 403 per il secondo. È una configurazione supportata, non un errore — alcune integrazioni vogliono i record senza le immagini.

Chieda quello che usa. Ventisei ambiti non sono un menù da spuntare: il ristorante legge l'elenco prima di dare il proprio consenso, e una richiesta per tutto impiega più tempo a passare di una richiesta per le quattro collezioni che il suo prodotto legge davvero.

Tre modalità di errore, deliberatamente distinte:

• 404 — la chiave non ha alcuna concessione per quel ristorante. L'API non rivela a un chiamante non autorizzato se un ristorante esiste.
• 403 — la chiave ha una concessione per quel ristorante, ma non l'ambito richiesto da questo endpoint.
• 401 — tra le altre cose, una chiave rimasta senza alcuna concessione. Una chiave privata della sua ultima concessione smette di autenticarsi anziché rispondere vuoto.

Per vedere cosa contiene davvero una chiave, glielo chieda: GET /v1/restaurants elenca i ristoranti con i loro ambiti, e GET /v1/restaurants/{id}/collections elenca le collezioni che apre.

Chi può emetterne una

Noi, su richiesta, e solo per i ristoranti che hanno dato il loro consenso. Veda Ottenere una chiave per cosa inviare e cosa si riceve.

Le concessioni vengono fissate quando la chiave viene predisposta e si cambiano solo con un'altra richiesta. Non esiste alcun percorso — né per lei né per noi — che ampli una chiave senza che il ristorante dia di nuovo il proprio consenso.

Scadenza e revoca

Una chiave non scade da sola, a meno che non ne abbia chiesta una che lo faccia. Resta valida finché non viene revocata.

La revoca è immediata: la richiesta successiva con quella chiave risponde 401, la stessa risposta che riceve una chiave sconosciuta o scaduta. Non si può annullare, e non serve — la sostituzione è una chiave nuova, non una ripristinata.

Ruotare senza interruzioni

Un'integrazione può avere due chiavi attive contemporaneamente, quindi la rotazione non richiede una finestra di manutenzione. Ci chieda di ruotare e questo è l'ordine in cui avviene:

1. Emettiamo una seconda chiave con gli stessi ristoranti e gli stessi ambiti.
2. Lei distribuisce il nuovo secret e ci dice quando è attivo ovunque.
3. Verifichiamo che la vecchia chiave non venga più usata — vediamo quando ogni chiave si è autenticata l'ultima volta, ed è il segnale che rende sicuro il passaggio 4.
4. Revochiamo la vecchia.

Ruoti con la cadenza che preferisce, e avvii la richiesta qualche giorno prima di quando vuole che la vecchia chiave sparisca: i passaggi 2 e 3 sono da coordinare tra lei e noi, e tutto il senso dell'ordine qui sopra è che nulla resti mai morto nemmeno per poco.

Igiene

• La conservi appena arriva ed elimini l'email. Fatto questo, il secret esiste esattamente in due posti: il suo gestore di secret e l'header Authorization.
• Una chiave per ogni deployment, non una per azienda. Una chiave di staging trapelata non deve mai diventare un incidente di produzione, e una revoca non deve mai far cadere più della cosa che è trapelata.
• Non ci mandi mai il secret — non in un ticket, non per identificare una chiave. Il prefisso pubblico la identifica senza ambiguità e può essere scritto ovunque senza rischi.
• Tenga d'occhio i 401 nel suo monitoraggio. Una chiave che comincia a fallire è stata revocata, e la risposta è una conversazione, non un ciclo di tentativi.