> ## 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. # Owner connect > Un host collega i suoi annunci su Gridbeds a un account da te, con un token firmato monouso e senza condividere dati di contatto. **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](/it/distribution-api/testing)). 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 L'host avvia in Gridbeds il collegamento del suo account con il tuo canale. 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`. 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. 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. 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. | Parte | | | - | - | | Intestazione | `alg` `ES256`, `typ` `owner-connect+jwt`, `kid` la chiave di firma. | | `iss` | L'origine dell'API: `https://api.gridbeds.com`, oppure `https://staging-api.gridbeds.com` sulla sandbox. | | `aud` | Il tuo canale: il `channel` di `GET /channel`. | | `sub` | L'id del proprietario. | | `property_ids` | Gli id delle strutture di quel proprietario che ti erano distribuite quando l'host ha avviato. | | `iat` | Quando è stato emesso. | | `exp` | Quando scade: al massimo 300 secondi dopo `iat`. | | `jti` | Un id casuale monouso di 128 bit. | | `locale` | La lingua dell'interfaccia dell'host (BCP 47). Può mancare. | 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 ```http theme={null} PUT /api/v1/distribution/owners/own_63g5d4zsqj809bf5rwekga54a5/connection HTTP/1.1 Host: api.gridbeds.com Authorization: Bearer gbd_live_… Content-Type: application/json {"token": "eyJ…"} ``` 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`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.