# Ottenere una chiave

> Come richiedere una chiave dell'API Partner, cosa indicare nella richiesta e cosa si riceve.

Source: https://developers.backresto.com/it/docs/access

Le chiavi partner sono emesse a mano. Compili il modulo qui sotto (oppure ci
scriva via email, che raggiunge le stesse persone) e noi predisponiamo la
credenziale e la inviamo al contatto che indica.

Ogni richiesta viene letta da una persona, perché una chiave dà accesso ai
registri di conformità di un ristorante e il ristorante deve avere dato il
proprio consenso. Quello che le costa è una risposta anziché un
reindirizzamento; quello che ottiene è che nessuno possa procurarsi da solo
l'accesso ai dati di qualcun altro. Il modulo chiede in una sola volta tutto ciò
che ci serve per dare seguito alla richiesta.

## Chi può richiederla

Entrambe le parti, ma in ogni caso il ristorante deve dare il consenso.

- **Lei, l'integratore.** Indichi di quali ristoranti ha bisogno e il nome del
  suo referente presso di loro; confermiamo con loro prima di emettere qualsiasi
  cosa.
- **Il ristorante.** Richiede per suo conto e la indica. È il percorso più
  rapido, perché la conferma è già avvenuta.

Non emettiamo una chiave per un ristorante che non ha dato il consenso, e non
ampliamo una chiave esistente senza chiederglielo di nuovo.

## Richiedere una chiave

To request a key, write to contact@backresto.com or fill in the form at https://developers.backresto.com/it/docs/access. Name the company, the product that will call the API, a technical contact, the restaurants and the scopes you need.

Se sta integrando per più ristoranti che appartengono a clienti diversi, invii
una richiesta per cliente. Una chiave per cliente evita che una revoca faccia
cadere tutte le altre integrazioni che gestisce.

Due dei campi meritano una nota. L'**ambiente** conta perché chiavi e dati sono
per ambiente: una chiave di produzione non significa nulla in pre-produzione,
quindi ci dica se vuole sviluppare prima sulla pre-produzione. E gli
**scope** dovrebbero essere quelli che usa, non tutti: sono ventisei, uno per
[collezione](https://developers.backresto.com/it/docs/collections), consegne e loro fotografie comprese, e il
ristorante legge quell'elenco prima di dare il proprio consenso. Indicare i
quattro che le servono ottiene un sì più rapido rispetto a chiederli tutti; veda
[Autenticazione](https://developers.backresto.com/it/docs/authentication) per cosa apre ciascuno.

Ha già una chiave e vuole una collezione che non raggiunge? È la stessa email,
ed è un'estensione anziché una chiave nuova: il suo secret non cambia e non
serve ridistribuire nulla.

Preferisce scriverla lei? [contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
con gli stessi dettagli raggiunge la stessa casella.

## Cosa si riceve

Un unico valore, nella forma `brp_<prefix>.<secret>`, inviato al contatto
tecnico che ha indicato.

**La conservi appena arriva ed elimini l'email.** Conserviamo solo il prefisso
pubblico e un digest del secret, quindi non possiamo reinviarla: se va persa
revochiamo quella chiave e ne emettiamo una nuova, il che significa un altro
giro.

Le chiavi non scadono da sole. Restano valide finché non vengono revocate, ed è
per questo che la risposta a «qualcuno ha lasciato il team» è una rotazione, non
un'alzata di spalle.

## Modificare una chiave in seguito

Per tutte queste cose basta una email, e tutte richiedono il consenso del
ristorante quando ampliano l'accesso:

| Richiesta | Cosa succede |
| --- | --- |
| **Aggiungere un ristorante o uno scope** | Estendiamo la chiave esistente. Il suo secret non cambia e non serve ridistribuire nulla. |
| **Ruotare** | Prima emettiamo una seconda chiave, lei la distribuisce, poi revochiamo la vecchia. Nessuna finestra in cui non funziona né l'una né l'altra. |
| **Revocare** | Immediato. La richiesta successiva con quella chiave risponde `401`. |
| **Una chiave a tempo** | Lo indichi nella richiesta: per un audit una tantum o un proof of concept, una chiave che muore da sola è più sicura di una che deve ricordarsi di eliminare. |

Per qualsiasi urgenza (soprattutto un secret trapelato) scriva a
[contact@backresto.com](mailto:contact@backresto.com?subject=Urgent%3A%20revoke%20Partner%20API%20key)
indicando il **prefisso pubblico** della chiave (la metà `brp_…` prima del
punto) e dicendo che è urgente. Non ci mandi mai il secret stesso, nemmeno per
dimostrare di quale chiave si tratta.

## Nel frattempo

Niente nella [documentazione](https://developers.backresto.com/it/docs) richiede una chiave per essere letto, e le
strutture sono tutte su queste pagine: [il record di consegna con le sue
fotografie](https://developers.backresto.com/it/docs/deliveries), [collezioni e record](https://developers.backresto.com/it/docs/collections),
[il modello di errore](https://developers.backresto.com/it/docs/errors) e [la paginazione](https://developers.backresto.com/it/docs/pagination).
Anche il [documento OpenAPI](https://api.backresto.com/openapi.json) è pubblico,
quindi può generare un client e scrivere il codice prima che arrivi la chiave.