Salt la conținutul principal
Fiecare cerere către API poartă o cheie, în antetul Authorization:
Singura excepție e vocabularul, GET /schema, care e public și nu cere cheie.

​
Ce face o cheie

O cheie acționează în numele contului care a creat-o. Poate face exact ce poate face contul în portal, cu aceleași limite:
  • anunțurile create prin API sunt ale contului, ca și cum le-ai fi adăugat din formular;
  • dacă ești membru al unei agenții, anunțul primește agenția, ca atunci când publici din cont;
  • dacă ești owner sau admin al agenției, vezi și gestionezi prin API și anunțurile colegilor tăi;
  • numele și emailul de contact ale anunțului sunt cele ale contului, iar telefonul e cel din cont, dacă nu trimiți altul în contact_phone.

​
Cum creezi o cheie

1

Deschide Setări → API

În producție, la housera.ro/setari/api. În sandbox, la https://staging.housera.ro/setari/api. Ai nevoie de un cont cu emailul confirmat.
2

Alege numele, drepturile și valabilitatea

Numele te ajută să recunoști cheia mai târziu (de exemplu crm-productie). Bifezi doar drepturile de care ai nevoie.
3

Copiază cheia

Cheia se arată o singură dată, imediat după creare. Housera nu o păstrează în clar, deci nu ți-o poate arăta din nou. Dacă ai pierdut-o, o revoci și creezi alta.

​
Drepturile

O integrare completă are nevoie de toate trei. Pentru un panou care doar afișează anunțurile, listings:read ajunge.

​
Prefixele

Prefixul îți spune imediat pe ce mediu merge o cheie: Cheia completă are forma <id>|hsr_live_<secret>. Trimiți tot șirul, cu id-ul și bara verticală.
Prefixele fixe fac cheile ușor de recunoscut de scanerele de secrete. Dacă o cheie ajunge din greșeală într-un depozit de cod public, revoc-o imediat.

​
Valabilitatea

Fiecare cheie expiră. La creare alegi 30, 90 sau 365 de zile. Data expirării se vede pe pagina Setări → API, lângă data creării și data ultimei folosiri. Când o cheie expiră, cererile primesc 401. Ca să nu ai întreruperi, creezi cheia nouă înainte de termen, o pui în sistemul tău, apoi o revoci pe cea veche. Un cont are cel mult 10 chei în același timp: destul pentru câte o cheie pe integrare, cu loc pentru o rotație.

​
Revocarea

Din Setări → API, revoci orice cheie cu un clic. Efectul e imediat: următoarea cerere cu acea cheie primește 401. Crearea și revocarea cheilor apar în jurnalul de activitate al contului.

​
Erorile de autentificare

Corpul e un obiect „problem details” (RFC 9457), cu un code stabil pe care îl poți testa în cod:
La 403, code e missing_ability când cheii îi lipsește dreptul cerut și forbidden în rest.
Nu pune niciodată cheia într-o aplicație care rulează în browser sau pe telefonul utilizatorului. Oricine o vede acolo poate publica în numele contului tău. Cheia stă doar pe serverul tău.