Autentificare
Fiecare cerere către API-ul public poartă o pereche de credențiale — nb_pub_* (cheie publică) + nb_sec_* (secret). Secretul este trimis ca token Bearer. Credențiala este restrânsă la o singură organizație + un catalog fix de scope-uri.
Emiterea credențialelor
- Autentificați-vă în organizația dvs. la app.nexbasira.com.
- Mergeți la Admin → Credențiale API.
- Faceți clic pe Emite credențială, alegeți un nume + scope-uri, confirmați.
- Copiați perechea
nb_pub_*+nb_sec_*. Secretul este afișat exact o singură dată. Stocați-l imediat în managerul dvs. de secrete — noi păstrăm doar un hash SHA-256 de partea noastră.
Utilizarea credențialei
Authorization: Bearer nb_sec_AbCdEf... Cheia publică (nb_pub_*) identifică credențiala în log-urile noastre + apare în antetul NB-Credential-Id al livrărilor de webhook. Secretul autentifică.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Catalog de scope-uri
Fiecare credențială este creată cu un set explicit de scope-uri. Cererile din afara acestor scope-uri returnează 403. Catalogul de scope-uri este fix (fără scope-uri personalizate la v1):
| Scope | Acordă |
|---|---|
sessions:read | Listare + obținere sesiuni |
sessions:write | Creare sesiuni + încheierea lor |
participants:read | Listarea participanților unei sesiuni |
participants:write | Emiterea invitațiilor pentru utilizatorii de teren |
evidence:read | Listare + obținere rânduri de probe + URL-uri de descărcare semnate |
recordings:read | Citirea metadatelor artefactelor de înregistrare + URL-uri de descărcare |
audit:read | Citirea lanțului de audit per sesiune + coordonatele ancorei TSA |
webhooks:read | Listarea endpoint-urilor webhook înregistrate + log-ul de livrare |
webhooks:write | Înregistrare / rotire-secret / ștergere endpoint-uri webhook |
branding:read | Citirea branding-ului organizației (siglă / culori / subsol PDF) |
branding:write | Modificarea branding-ului organizației |
org:read | Citirea metadatelor organizației |
whiteboards:read | Listarea tablourilor per sesiune |
Rotire
Pentru a roti fără întrerupere:
- Emiteți o credențială nouă cu același set de scope-uri.
- Implementați noul secret în aplicația dvs.
- Verificați că noua credențială preia traficul (Admin → Credențiale API afișează marcajul temporal al ultimei utilizări).
- Revocați soft vechea credențială. Cererile existente care o folosesc primesc 401; urma de audit a apelurilor trecute rămâne intactă.
Verificare în timp constant
Pe backend, secretele sunt stocate ca SHA-256(secret + SECRET_KEY_pepper) și comparate în timp constant (hmac.compare_digest). Un dump de hash-uri divulgat nu poate fi spart prin forță brută în text clar fără a sparge și pepper-ul.
Ce NU acordă această credențială
- Acces de administrare SPA — acela este separat (login operator + RBAC).
- Alăturarea de partea de teren — aceea folosește URL-uri semnate de unică folosință emise prin
sessions.invite(). - Provisioning SCIM — folosește un token bearer separat per organizație, vedeți provisioning SCIM.
- Semnarea webhook-urilor — aceea se face cu secretul
whsec_*per endpoint, vedeți Webhook-uri.
Urmă de audit
Fiecare apel API este logat cu cheia publică a credențialei + endpoint-ul + statusul. Operațiile care modifică starea scriu suplimentar rânduri de audit în organizația afectată. Adminul poate vedea activitatea credențialei la Admin → Credențiale API → [credențială] → Activitate.