> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticazione

> Le chiavi dell'API di distribuzione: chi le rilascia, come inviarle, i permessi che portano e come ruotarle.

<Warning>
  **Anteprima: non è ancora attivo nulla.** Qui è descritto il contratto dell'API di distribuzione (versione `1.0.0`). Nessuna chiave è ancora stata rilasciata; la prima chiave di test apre la sandbox.
</Warning>

## Chiavi

Una chiave appartiene al tuo canale e a un solo ambiente. Te la rilascia il team di Gridbeds, non le singole strutture: gli host scelgono quali delle loro strutture pubblicare sul tuo canale, e la tua chiave legge quello che hanno pubblicato.

* Una chiave di produzione inizia con `gbd_live_`, una di sandbox con `gbd_test_`. Una chiave è lunga 63 caratteri.
* Una chiave termina con un checksum CRC32 della sua parte segreta, quindi una chiave scritta male o troncata viene rifiutata prima di qualsiasi ricerca, e così una chiave usata nell'altro ambiente.
* Gridbeds conserva solo un hash di ogni chiave. Tieni la tua in un archivio di segreti, mai nel codice.
* I prefissi sono registrati presso gli scanner pubblici di segreti (GitHub secret scanning, TruffleHog, GitGuardian). Una chiave trovata in un repository pubblico viene revocata subito, e il tuo referente tecnico viene avvisato.

Invia la chiave come bearer token con ogni richiesta:

```http theme={null}
GET /api/v1/distribution/channel HTTP/1.1
Host: api.gridbeds.com
Authorization: Bearer gbd_live_…
```

## Rotazione

Durante una rotazione il tuo canale può avere due chiavi per ambiente: metti in servizio la chiave nuova, controlla che le richieste con quella vadano a buon fine, poi la vecchia può essere revocata. `GET /channel` mostra quale chiave ha usato una richiesta (`key.last4`), quando è stata creata e quando scade (`key.expires_at`, `null` per una chiave rilasciata senza scadenza).

## Permessi

Ogni operazione indica i permessi (scope) che richiede. Una chiave ne ha uno o più:

| Permesso | Dà accesso a |
| - | - |
| `read:catalog` | Sedi, proprietari, strutture, il catalogo dei servizi e i relativi eventi. |
| `read:ari` | Disponibilità, prezzi e restrizioni, e gli eventi `availability.updated`. |
| `manage:webhooks` | I tuoi endpoint webhook, i loro segreti e le loro consegne. |

`GET /channel` non richiede permessi. `write:bookings` è riservato a una fase successiva e non viene concesso. I permessi sono scope OAuth 2.0, quindi in futuro, accanto alle chiavi, si potranno offrire token di accesso a breve durata con un grant client-credentials, con gli stessi permessi e senza cambiare nessuna operazione.

## Quando una chiave viene rifiutata

Una chiave rifiutata riceve `401` con `WWW-Authenticate` (RFC 6750) e un problema il cui `code` dice perché:

| `code` | Significa |
| - | - |
| `missing_api_key` | Manca l'intestazione `Authorization: Bearer`. |
| `invalid_api_key` | La chiave è malformata o sconosciuta: i due casi ricevono la stessa risposta. |
| `api_key_wrong_environment` | Una chiave `gbd_test_` in produzione, o una chiave `gbd_live_` in sandbox. |
| `api_key_expired` | La chiave è scaduta. |
| `api_key_revoked` | La chiave è stata revocata. |

`api_key_expired` e `api_key_revoked` si distinguono solo per una chiave il cui segreto corrisponde. Una chiave senza il permesso richiesto da un'operazione riceve `403` con `insufficient_scope` e i permessi mancanti in `required_scopes`; un canale sospeso riceve `403` con `partner_suspended`. Ripetuti tentativi di autenticazione falliti dallo stesso indirizzo ricevono `429` (`too_many_failed_authentications`). Vedi [Errori e limiti](/it/distribution-api/errors-and-limits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.