Chei API

API-ul de administrare a cheilor API este echivalentul programatic al ecranului Setări → Chei API din Portal. Le permite Owner-ilor și Admin-ilor unei organizații să creeze, listeze, redenumească, dezactiveze și revoce chei API fără să treacă prin UI — util pentru provisioning de integrări, rotirea cheilor dintr-un pipeline CI sau auditarea setului de chei active dintr-un instrument de back-office.

Toate endpoint-urile din acest grup sunt sub /api/v1/org/api-keys și sunt administrative, la fel ca endpoint-urile de administrare a Webhook-urilor.

Plicul de eroare, limitele de rată și convențiile de paginare sunt documentate o singură dată pe Prezentare API; pe această pagină listăm doar codurile de eroare specifice fiecărui endpoint.

Permisiuni

POST /api/v1/org/api-keys cere cel puțin o permisiune. Permisiunile disponibile sunt:

Catalogul complet de permisiuni, inclusiv ce rute acceptă ce permisiuni, este pe Autentificare › Permisiuni.

GET /api/v1/org/api-keys

Listează toate cheile API ale organizației, cele mai noi primele. Cheia hash-uită nu este returnată niciodată; doar prefixul (primele 12 caractere ale cheii originale plus …) este expus, ca să poți identifica ce cheie e care.

• Autentificare: JWT din Portal.

Răspuns (200 OK)

[
  {
    "id": "apikey_abc123",
    "prefix": "ebon_live_a…",
    "label": "Integrare contabilitate",
    "scopes": ["receipts", "reports"],
    "active": true,
    "createdAt": "2026-03-01T12:00:00.000Z",
    "lastUsed": "2026-04-09T08:09:55.000Z",
    "expiresAt": "2027-03-01T12:00:00.000Z",
    "rotatedFromId": null,
    "rotatedToId": null
  }
]

lastUsed este null pentru cheile care nu au fost folosite niciodată ca să autentifice o cerere. expiresAt este null pentru cheile care nu expiră niciodată. rotatedFromId și rotatedToId leagă o cheie de predecesorul / succesorul ei atunci când a fost rotită; ambele sunt null pentru cheile care nu au fost rotite niciodată.

Exemplu

curl https://api.e-bon.ro/api/v1/org/api-keys \
  -H "Authorization: Bearer <portal-jwt>"

Coduri de eroare

• UNAUTHORIZED (401) — JWT lipsă sau invalid.

Catalogul HTTP complet este pe Prezentare API › Catalogul codurilor de eroare HTTP.

POST /api/v1/org/api-keys

Generează o cheie API nouă cu eticheta și permisiunile specificate. Secretul brut este returnat o singură dată în câmpul key al răspunsului — stocheaz-o imediat.

• Autentificare: JWT din Portal, rol Owner sau Admin.
• Verificare plan: cererea trece prin middleware-ul enforceApiKeyCreation. Planul Free nu permite crearea de chei API; cererea este respinsă cu 403 TIER_LIMIT_EXCEEDED.

Corpul cererii

Răspuns (201 Created)

{
  "id": "apikey_abc123",
  "key": "ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "prefix": "ebon_live_a…",
  "label": "Integrare contabilitate",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-04-09T08:10:00.000Z",
  "expiresAt": "2027-04-09T08:10:00.000Z"
}

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/org/api-keys \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Integrare contabilitate",
    "scopes": ["receipts", "reports"],
    "expiresAt": "2027-04-09T08:10:00.000Z"
  }'

Coduri de eroare

• VALIDATION_ERROR (400) — corpul nu a trecut validarea Zod (etichetă goală, etichetă > 100 caractere, array scopes gol, valoare de permisiune necunoscută, expiresAt nu este un timestamp ISO 8601 valid sau expiresAt nu este în viitor).
• UNAUTHORIZED (401) — JWT lipsă sau invalid, sau cheia API a expirat (când e folosită pentru a autentifica cereri ulterioare; mesaj de eroare: API key has expired.).
• FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
• TIER_LIMIT_EXCEEDED (403) — cheile API nu sunt disponibile pe planul Free; treci pe Pro ca să creezi chei API.

PATCH /api/v1/org/api-keys/{keyId}

Actualizează label și/sau starea active a unei chei API. Cel puțin un câmp trebuie furnizat. Permisiunile sunt imutabile — ca să schimbi setul de permisiuni, revocă cheia și creează una nouă.

• Autentificare: JWT din Portal, rol Owner sau Admin.

Parametri de cale

Corpul cererii

Răspuns (200 OK)

{
  "id": "apikey_abc123",
  "prefix": "ebon_live_a…",
  "label": "Integrare contabilitate (redenumită)",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-03-01T12:00:00.000Z",
  "lastUsed": "2026-04-09T08:09:55.000Z",
  "expiresAt": null,
  "rotatedFromId": null,
  "rotatedToId": null
}

Exemplu

curl -X PATCH https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123 \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Coduri de eroare

• VALIDATION_ERROR (400) — corpul nu a trecut validarea Zod sau e gol (niciun câmp de actualizat).
• UNAUTHORIZED (401) — JWT lipsă sau invalid.
• FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
• NOT_FOUND (404) — nu există nicio cheie API cu acel ID în organizația ta.

POST /api/v1/org/api-keys/{keyId}/rotate

Rotește o cheie API. Într-o singură tranzacție atomică Firestore, cheia existentă este dezactivată și o cheie nouă cu aceeași etichetă, aceleași permisiuni și același expiresAt este generată. rotatedToId al cheii vechi indică spre cheia nouă; rotatedFromId al cheii noi indică spre cea veche. Secretul brut al cheii noi este returnat o singură dată în câmpul key — stocheaz-l înainte ca răspunsul să fie aruncat.

Folosește această operație când suspectezi că o cheie s-a scurs, când o integrare necesită o rotație periodică sau ca parte dintr-o politică de igienă programată. Pentru că operația e atomică, nu există o fereastră în care ambele chei sunt active sau ambele sunt inactive.

• Autentificare: JWT din Portal, rol Owner sau Admin.

Parametri de cale

Corpul cererii

Gol — nu sunt acceptate câmpuri în corp.

Răspuns (201 Created)

{
  "id": "apikey_xyz789",
  "key": "ebon_live_acme_corp_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4",
  "prefix": "ebon_live_z…",
  "label": "Integrare contabilitate",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-09-15T10:00:00.000Z",
  "expiresAt": "2027-04-09T08:10:00.000Z",
  "rotatedFromId": "apikey_abc123"
}

După rotație, cheia veche (apikey_abc123) are active: false și rotatedToId: "apikey_xyz789"; poate fi inspectată în continuare prin GET /api/v1/org/api-keys pentru audit, dar va fi respinsă la nivel de auth.

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123/rotate \
  -H "Authorization: Bearer <portal-jwt>"

Coduri de eroare

• UNAUTHORIZED (401) — JWT lipsă sau invalid.
• FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
• NOT_FOUND (404) — nu există nicio cheie API cu acel ID în organizația ta.
• CONFLICT (409) — cheia este deja inactivă (a fost revocată anterior sau deja rotită); rotația se aplică doar cheilor active.

DELETE /api/v1/org/api-keys/{keyId}

Revocă definitiv o cheie API. Cheia este eliminată din Firestore — nu există soft-delete. Cererile în curs autentificate cu acea cheie continuă să se finalizeze; cererile ulterioare sunt respinse cu 401 UNAUTHORIZED. Returnează 204 No Content la succes.

• Autentificare: JWT din Portal, rol Owner sau Admin.

Parametri de cale

Exemplu

curl -X DELETE https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123 \
  -H "Authorization: Bearer <portal-jwt>"

Coduri de eroare

• UNAUTHORIZED (401) — JWT lipsă sau invalid.
• FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
• NOT_FOUND (404) — nu există nicio cheie API cu acel ID în organizația ta.

Vezi și

• Autentificare — formatul cheilor API, catalogul de permisiuni, fluxul de login JWT și erori de autentificare.
• Comenzi, Bonuri, Dispozitive — endpoint-urile care consumă cheile generate aici.
• Prezentare API — URL de bază, plic de eroare, limite de rată, idempotență, paginare.