# Autenticazione > Le chiavi partner, i ventisei scope, cosa significa una concessione e come ruotare senza interruzioni. Source: https://developers.backresto.com/it/docs/authentication Ogni richiesta all'API Partner porta una sola credenziale, nel posto standard: ```http Authorization: Bearer brp_. ``` 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. | Metà | Che cos'è | Dove può comparire | | --- | --- | --- | | `brp_` | Un identificatore pubblico della credenziale. | I suoi log, una email al supporto, l'elenco delle chiavi su questo sito. | | `` | 256 bit casuali. | Il suo gestore di secret e l'header `Authorization`. | 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 × scope Una chiave non è «un account con dei permessi». È un elenco di concessioni esplicite, ognuna una coppia: Ci sono **ventisei scope**, e vale la pena imparare la grammatica una volta per tutte: | Scope | Dà accesso a | | --- | --- | | `:read` | Una delle [ventisei collezioni](https://developers.backresto.com/it/docs/collections): `deliveries:read`, `delivery-pictures:read`, `cooling:read`, `temperature-records:read`, `traceability-labels:read` e così via, uno scope per collezione. | Ogni scope termina con `:read`. Non esiste alcuno scope 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-pictures:read` solo su `restaurant-1`, legge le fotografie delle consegne 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 scope 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 rispetto a 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 lo scope 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 scope, e [`GET /v1/restaurants/{id}/collections`](https://developers.backresto.com/it/docs/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](https://developers.backresto.com/it/docs/access) 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 scope. 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 fuori servizio, 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 mettere fuori uso più di ciò che è trapelato. - **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.