Autentificare

Fiecare cerere către /api/v1/* trebuie să includă un antet Authorization:

Authorization: Bearer <slug-tenant>.<cheie>

<slug-tenant> este subdomeniul tenantului tău (ex. wartung pentru wartung.notsocrm.ro) — el spune platformei în ce bază de date să caute cheia, înainte ca cheia însăși să fie validată. <cheie> este cheia API generată din interfața web.

Generarea unei chei

Cheile se creează din Administrare → Chei API. La generare, platforma îți afișează cheia completă o singură dată — după ce închizi ecranul, doar valoarea mascată (primele caractere + ...) mai rămâne vizibilă. Dacă pierzi cheia, generează una nouă; cea veche poate fi revocată separat.

Capabilități (permisiuni)

O cheie API are un set de capabilități, fiecare în forma <resursă>:<acțiune>. O cerere este respinsă cu 403 dacă cheia nu are capabilitatea cerută de endpoint.

Resursă	Etichetă	Acțiuni disponibile
companies	Companii	read, write
contacts	Contacte	read, write
addresses	Adrese	read, write
tickets	Tichete	read, write
billing	Facturare	read, write

Acțiunea cerută este read pentru GET/HEAD și write pentru orice altă metodă. Resursa este dedusă din calea cererii (de exemplu POST /api/v1/companies/5/contacts cere contacts:write, nu companies:write).

O cheie poate primi capabilitatea specială *, care înlocuiește orice combinație resursă:acțiune — echivalentul acces total. O cheie fără nicio capabilitate înregistrată (permissions gol) nu are acces la nimic; platforma nu acordă acces implicit unei chei fără permisiuni explicite.

Restricție IP (opțional)

O cheie poate fi limitată la o listă de adrese IP permise. Dacă lista este goală, cheia este acceptată de la orice IP. Dacă lista conține una sau mai multe adrese, cererile de la orice alt IP primesc 403.

Limită de rată

Fiecare cheie are o limită orară de cereri, rate_limit_per_hour (implicit 1000, configurabilă per cheie). Fiecare răspuns include:

Antet	Descriere
X-RateLimit-Limit	Limita orară configurată pentru cheie.
X-RateLimit-Remaining	Câte cereri mai poți face în fereastra curentă.

Când limita este depășită, cererea primește 429 și un antet suplimentar:

Antet	Descriere
Retry-After	Numărul de secunde până se reface fereastra de rată.

{ "error": "Rate limit exceeded." }