> ## Documentation Index
> Fetch the complete documentation index at: https://api.housera.ro/llms.txt
> Use this file to discover all available pages before exploring further.

# Autentificare

> Cheile API: cum le creezi, ce drepturi au, cât sunt valabile și cum le revoci.

Fiecare cerere către API poartă o cheie, în antetul `Authorization`:

```http theme={null}
Authorization: Bearer 12|hsr_live_9fQ2kX...
Accept: application/json
```

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

<Steps>
  <Step title="Deschide Setări → API">
    În producție, la [housera.ro/setari/api](https://housera.ro/setari/api). În sandbox, la `https://staging.housera.ro/setari/api`. Ai nevoie de un cont cu emailul confirmat.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Drepturile

| Drept | Ce permite |
| - | - |
| `listings:read` | Citești anunțurile tale (`GET /account/listings`, `GET /account/listings/{code}`, `GET /account/listings/ref/{ref}`) și evenimentele (`GET /events`). |
| `listings:write` | Creezi, validezi, editezi și ștergi anunțuri, le marchezi vândute, le pui pe pauză sau le reactivezi. |
| `media:write` | Pregătești uploaduri (`POST /uploads`) și setezi pozele unui anunț (`PUT /listings/{code}/photos`). |

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:

| Prefix | Mediu |
| - | - |
| `hsr_test_` | Sandbox (`https://staging.housera.ro/api/v1`) |
| `hsr_live_` | Producție (`https://housera.ro/api/v1`) |

Cheia completă are forma `<id>|hsr_live_<secret>`. Trimiți tot șirul, cu id-ul și bara verticală.

<Tip>
  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.
</Tip>

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

| Status | Când |
| - | - |
| `401 Unauthorized` | Lipsește antetul `Authorization`, cheia e greșită, expirată sau revocată, ori contul nu mai e activ. |
| `403 Forbidden` | Cheia e validă, dar nu are dreptul cerut de endpoint (de exemplu `PUT /listings/{code}/photos` fără `media:write`). |

Corpul e un obiect „problem details” (RFC 9457), cu un `code` stabil pe care îl poți testa în cod:

```json theme={null}
{
  "type": "https://housera.ro/problems/unauthenticated",
  "title": "Lipsește cheia API sau nu mai e valabilă.",
  "status": 401,
  "code": "unauthenticated",
  "detail": "Lipsește cheia API sau nu mai e valabilă."
}
```

La `403`, `code` e `missing_ability` când cheii îi lipsește dreptul cerut și `forbidden` în rest.

<Warning>
  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.
</Warning>


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