Skip to main content
Non ancora attivo. Qui è descritto il contratto definitivo, versione 1.0.0. Finché la sandbox non apre con la prima chiave di test, provalo su un mock del contratto (Test).
Owner connect permette a un host di collegare i suoi annunci su Gridbeds a un account da te. Gridbeds non condivide nessun indirizzo e-mail né altro dato di contatto dell’host per farlo: niente dell’host ti arriva se non tramite questa azione. Confermare e rimuovere un collegamento richiede il permesso write:listings.

​
Prima di iniziare

Registra presso Gridbeds il tuo URL di reindirizzamento: la pagina HTTPS pubblica a cui il browser dell’host invia il token. Registralo una volta per ogni ambiente, perché la sandbox e la produzione hanno ognuna la sua scheda del tuo canale: il tuo sito di staging sulla sandbox, quello pubblico in produzione. GET /channel restituisce quello dell’ambiente della chiave in owner_connect.redirect_url. È null finché non lo registri, e fino ad allora gli host non possono avviare un collegamento con il tuo canale.

​
I passaggi

1

L'host avvia

L’host avvia in Gridbeds il collegamento del suo account con il tuo canale.
2

Il suo browser ti invia il token

Gridbeds risponde all’host con un modulo HTML che il browser invia subito al tuo URL di reindirizzamento: un POST di modulo (application/x-www-form-urlencoded) il cui unico campo è token. Il token non compare mai in un URL, in un log del server, nella cronologia del browser o in un Referer.
3

Lo verifichi e lo tieni sul server

Verifica il token come spiegato sotto e conservalo sul tuo server, poi rispondi con un 303 verso una delle tue pagine. Il POST arriva da un altro sito, quindi il browser non invia con esso i tuoi cookie marcati SameSite=Lax o Strict; sulla tua pagina la sessione dell’host torna disponibile. Per un token non valido, scaduto o già usato, mostra una pagina che dice che il collegamento non è riuscito: l’host può ricominciare da Gridbeds.
4

L'host accede e conferma

Fai accedere l’host o fagli creare un account da te (l’indirizzo e-mail, se ti serve, lo digita l’host lì), poi chiedi all’host che ha effettuato l’accesso di confermare il collegamento sulla tua pagina, mostrando il display_name del proprietario.
5

Colleghi e confermi

Collega il sub del token, un id di proprietario che hai da GET /owners, a quell’account, e invia il token a PUT /owners/{owner_id}/connection. Il connected_at del proprietario viene impostato (owner.updated), e l’host vede l’account collegato in Gridbeds.
Non collegare mai in base al solo POST. Qualsiasi sito può far inviare un modulo a un browser, quindi un token inviato senza la conferma dell’host potrebbe collegare il proprietario di qualcun altro all’account che in quel momento ha effettuato l’accesso.

​
Il token

Il token è un JWS in serializzazione compatta (RFC 7515; un JWT, RFC 7519) firmato con ES256. Verifica tutto prima di fidarti di qualsiasi dato:
  • La firma, con la chiave indicata da kid in GET /owner-connect/keys: un JWKS (RFC 7517) di chiavi pubbliche EC P-256 per ES256, pubblico, senza bisogno di chiave e limitato per indirizzo del client. Tienilo in cache come dice il suo Cache-Control, e richiedilo quando un token indica un kid che non hai. Una nuova chiave di firma viene pubblicata almeno 24 ore prima che firmi, e una ritirata resta pubblicata 24 ore dopo che smette.
  • alg esattamente ES256 e typ esattamente owner-connect+jwt, rifiutando none e ogni altro valore (RFC 8725).
  • iss e aud come sopra. Un token emesso in un ambiente si verifica solo con l’iss e le chiavi di quell’ambiente.
  • exp nel futuro e iat non nel futuro, con al massimo 60 secondi di scarto dell’orologio.
  • sub un proprietario che ti è distribuito.

​
Due scadenze

  • exp limita il passaggio dal browser. Cade al massimo 300 secondi dopo iat, e la tua pagina di reindirizzamento accetta il token solo prima.
  • La conferma può arrivare dopo, perché l’host potrebbe dover prima creare un account. PUT /owners/{owner_id}/connection accetta un token non ancora confermato fino a 3600 secondi dopo il suo iat, e solo dal canale indicato nel suo aud, con la chiave di quel canale. Nel frattempo tieni il token verificato sul server, mai in una pagina o in un URL.

​
Riutilizzo

Un token è monouso. Conserva ogni jti che accetti fino al suo exp, e rifiuta quelli che hai già visto. Gridbeds lega un token all’unico collegamento che conferma: confermarlo di nuovo per lo stesso proprietario restituisce lo stesso collegamento, e ogni altro uso viene rifiutato.

​
Conferma e rimuovi un collegamento

Il sub del token deve essere questo proprietario, il suo aud il tuo canale e il suo iat di al massimo 3600 secondi fa. La risposta è il collegamento, {owner_id, connected_at}. Un rifiuto è 400 invalid_parameters con errors[].pointer /token ed errors[].code token_invalid, token_expired, token_owner_mismatch o token_used. Quando l’host scollega l’account da te, invia DELETE /owners/{owner_id}/connection: il connected_at del proprietario diventa null (owner.updated), e cancellare un collegamento che non esiste risponde comunque 204. connected_at diventa null anche quando l’host si scollega in Gridbeds, e ti arriva come owner.updated.