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.
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:
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ù:
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é:
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.
