> ## 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

> O gazdă își leagă listările din Gridbeds de un cont la tine, cu un token semnat de unică folosință și fără să se transmită date de contact.

<Warning>
  **Încă nu este servit.** Pagina descrie contractul final, versiunea `1.0.0`. Până se deschide sandbox-ul, odată cu prima cheie de test, încearcă-l pe un mock al contractului ([Testare](/ro/distribution-api/testing)).
</Warning>

Owner connect îi permite unei gazde să își lege listările din Gridbeds de un cont la tine. Gridbeds nu transmite nicio adresă de e-mail și nicio altă dată de contact a gazdei pentru asta: nimic despre gazdă nu ajunge la tine decât prin această acțiune. Confirmarea și ștergerea unei conexiuni cer permisiunea `write:listings`.

## Înainte să începi

Înregistrează la Gridbeds URL-ul tău de redirecționare: pagina HTTPS publică la care browserul gazdei trimite token-ul. Înregistrează-l o dată pentru fiecare mediu, pentru că sandbox-ul și producția au fiecare propria evidență a canalului tău: site-ul tău de staging pe sandbox, site-ul live în producție. `GET /channel` îl dă pe cel din mediul cheii în `owner_connect.redirect_url`. Este `null` până îl înregistrezi, iar până atunci gazdele nu pot porni o conexiune cu canalul tău.

## Pașii

<Steps>
  <Step title="Gazda pornește">
    Gazda pornește conectarea contului ei cu canalul tău din Gridbeds.
  </Step>

  <Step title="Browserul ei îți trimite token-ul">
    Gridbeds îi răspunde gazdei cu un formular HTML pe care browserul îl trimite imediat la URL-ul tău de redirecționare: un POST de formular (`application/x-www-form-urlencoded`) al cărui singur câmp este `token`. Token-ul nu apare niciodată într-un URL, într-un jurnal de server, în istoricul browserului sau într-un `Referer`.
  </Step>

  <Step title="Îl verifici și îl păstrezi pe server">
    Verifică token-ul ca mai jos și păstrează-l pe serverul tău, apoi răspunde cu un `303` către una dintre paginile tale. POST-ul vine de pe alt site, așa că browserul nu trimite odată cu el cookie-urile tale marcate `SameSite=Lax` sau `Strict`; pe pagina ta sesiunea gazdei este din nou disponibilă. Pentru un token invalid, expirat sau refolosit, arată o pagină care spune că legătura nu a reușit: gazda poate porni din nou din Gridbeds.
  </Step>

  <Step title="Gazda se autentifică și confirmă">
    Lasă gazda să se autentifice sau să își facă un cont la tine (gazda își tastează acolo propria adresă de e-mail, dacă ai nevoie de una), apoi cere-i gazdei autentificate să confirme legătura pe pagina ta, arătând `display_name`-ul proprietarului.
  </Step>

  <Step title="Legi și confirmi">
    Leagă `sub`-ul token-ului, un id de proprietar pe care îl ai din `GET /owners`, de acel cont și trimite token-ul la `PUT /owners/{owner_id}/connection`. `connected_at` al proprietarului este setat (`owner.updated`), iar gazda vede contul conectat în Gridbeds.
  </Step>
</Steps>

**Nu lega niciodată doar pe baza POST-ului.** Orice site poate face un browser să trimită un formular, așa că un token trimis fără confirmarea gazdei ar putea lega proprietarul altcuiva de contul care se întâmplă să fie autentificat.

## Token-ul

Token-ul este un JWS în serializare compactă (RFC 7515; un JWT, RFC 7519), semnat cu ES256.

| Parte | |
| - | - |
| Antet | `alg` `ES256`, `typ` `owner-connect+jwt`, `kid` cheia de semnare. |
| `iss` | Originea API-ului: `https://api.gridbeds.com` sau, pe sandbox, `https://staging-api.gridbeds.com`. |
| `aud` | Canalul tău: `channel` din `GET /channel`. |
| `sub` | Id-ul proprietarului. |
| `property_ids` | Id-urile proprietăților acelui proprietar care îți erau distribuite când a pornit gazda. |
| `iat` | Când a fost emis. |
| `exp` | Când expiră: cel mult 300 de secunde după `iat`. |
| `jti` | Un id aleatoriu de unică folosință, de 128 de biți. |
| `locale` | Limba interfeței gazdei (BCP 47). Poate lipsi. |

Verifică tot înainte să te bazezi pe vreo afirmație din el:

* **Semnătura**, cu cheia numită de `kid` în `GET /owner-connect/keys`: un JWKS (RFC 7517) de chei publice EC P-256 pentru ES256, public, fără cheie de acces și limitat pe adresa clientului. Păstrează-l în cache cât spune `Cache-Control`-ul lui și cere-l din nou când un token numește un `kid` pe care nu îl ai. O cheie de semnare nouă este publicată cu cel puțin 24 de ore înainte să semneze, iar una retrasă rămâne publicată 24 de ore după ce nu mai semnează.
* **`alg` exact `ES256` și `typ` exact `owner-connect+jwt`**, refuzând `none` și orice altă valoare (RFC 8725).
* **`iss` și `aud`** ca mai sus. Un token emis într-un mediu se verifică doar cu `iss`-ul și cheile acelui mediu.
* **`exp` în viitor și `iat` nu în viitor**, cu o abatere a ceasului de cel mult 60 de secunde.
* **`sub` un proprietar care îți este distribuit.**

## Două termene

* **`exp` limitează drumul prin browser.** Este la cel mult 300 de secunde după `iat`, iar pagina ta de redirecționare acceptă token-ul doar înainte de el.
* **Confirmarea poate veni mai târziu**, pentru că gazda poate fi nevoită să își facă întâi un cont. `PUT /owners/{owner_id}/connection` acceptă un token neconfirmat până la 3600 de secunde după `iat`-ul lui, și doar de la canalul numit în `aud`, cu cheia proprie a acelui canal. Între timp păstrează token-ul verificat pe server, niciodată într-o pagină sau într-un URL.

## Refolosirea

Un token este de unică folosință. Păstrează fiecare `jti` acceptat până la `exp`-ul lui și refuză unul pe care l-ai mai văzut. Gridbeds leagă un token de singura conexiune pe care o confirmă: confirmarea lui din nou pentru același proprietar răspunde cu aceeași conexiune, iar orice altă folosire este refuzată.

## Confirmă și șterge o conexiune

```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…"}
```

`sub`-ul token-ului trebuie să fie acest proprietar, `aud`-ul canalul tău, iar `iat`-ul de cel mult 3600 de secunde în urmă. Răspunsul este conexiunea, `{owner_id, connected_at}`. Un refuz este `400` `invalid_parameters` cu `errors[].pointer` `/token` și `errors[].code` `token_invalid`, `token_expired`, `token_owner_mismatch` sau `token_used`.

Când gazda deconectează contul la tine, trimite `DELETE /owners/{owner_id}/connection`: `connected_at` al proprietarului devine `null` (`owner.updated`), iar ștergerea unei conexiuni care nu există răspunde tot cu `204`. `connected_at` devine `null` și când gazda se deconectează din Gridbeds, ceea ce ajunge la tine ca `owner.updated`.


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