Autenticazione
Ogni richiesta all'API pubblica porta una coppia di credenziali — nb_pub_* (chiave pubblica) + nb_sec_* (secret). Il secret viene inviato come Bearer token. La credenziale è vincolata a una singola org + un catalogo di scope fisso.
Emettere le credenziali
- Accedi alla tua org su app.nexbasira.com.
- Vai su Admin → API credentials.
- Clicca Issue credential, scegli un nome + scope, conferma.
- Copia la coppia
nb_pub_*+nb_sec_*. Il secret viene mostrato esattamente una volta. Salvalo subito nel tuo secrets manager — dal nostro lato conserviamo solo un hash SHA-256.
Usare la credenziale
Authorization: Bearer nb_sec_AbCdEf... La chiave pubblica (nb_pub_*) identifica la credenziale nei nostri log + appare nell'header NB-Credential-Id dei recapiti dei webhook. Il secret autentica.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Catalogo degli scope
Ogni credenziale viene creata con un set di scope esplicito. Le richieste fuori da quegli scope restituiscono 403. Il catalogo degli scope è fisso (nessuno scope personalizzato in v1):
| Scope | Concede |
|---|---|
sessions:read | Elenca + recupera sessioni |
sessions:write | Crea sessioni + terminale |
participants:read | Elenca i partecipanti di una sessione |
participants:write | Genera inviti per utenti sul campo |
evidence:read | Elenca + recupera righe di prove + URL di download firmati |
recordings:read | Leggi i metadati degli artefatti di registrazione + URL di download |
audit:read | Leggi la catena di audit per-sessione + le coordinate di ancoraggio TSA |
webhooks:read | Elenca gli endpoint webhook registrati + il log dei recapiti |
webhooks:write | Registra / rotate-secret / elimina endpoint webhook |
branding:read | Leggi il branding dell'org (logo / colori / footer PDF) |
branding:write | Modifica il branding dell'org |
org:read | Leggi i metadati dell'org |
whiteboards:read | Elenca le lavagne per sessione |
Rotazione
Per ruotare senza downtime:
- Emetti una nuova credenziale con lo stesso set di scope.
- Distribuisci il nuovo secret alla tua applicazione.
- Verifica che la nuova credenziale stia ricevendo traffico (Admin → API credentials mostra il timestamp dell'ultimo utilizzo).
- Revoca in modo soft la vecchia credenziale. Le richieste esistenti che la usano ricevono 401; la traccia di audit delle chiamate passate resta intatta.
Verifica a tempo costante
Sul backend, i secret sono memorizzati come SHA-256(secret + SECRET_KEY_pepper) e confrontati a tempo costante (hmac.compare_digest). Un dump di hash trafugato non può essere forzato a brute-force nel testo in chiaro senza rompere anche il pepper.
Cosa questa credenziale NON concede
- Accesso admin alla SPA — è separato (login operatore + RBAC).
- Ingresso lato campo — quelli usano URL firmate monouso generate tramite
sessions.invite(). - Provisioning SCIM — usa un bearer token separato per-org, vedi Provisioning SCIM.
- Firma dei webhook — questa avviene con il secret
whsec_*per-endpoint, vedi Webhooks.
Traccia di audit
Ogni chiamata API viene registrata con la chiave pubblica della credenziale + l'endpoint + lo stato. Le operazioni che modificano lo stato scrivono inoltre righe di audit nell'org interessata. L'admin può vedere l'attività della credenziale su Admin → API credentials → [credential] → Activity.