Authenticatie
Elk verzoek aan de publieke API draagt een credentialpaar — nb_pub_* (publieke sleutel) + nb_sec_* (secret). Het secret wordt als Bearer-token verzonden. De credential is beperkt tot één org + een vaste scope-catalogus.
Credentials uitgeven
- Log in bij uw org op app.nexbasira.com.
- Ga naar Admin → API-credentials.
- Klik op Credential uitgeven, kies een naam + scopes, bevestig.
- Kopieer het
nb_pub_*- +nb_sec_*-paar. Het secret wordt precies één keer getoond. Sla het direct op in uw secrets manager — wij bewaren alleen een SHA-256-hash aan onze kant.
De credential gebruiken
Authorization: Bearer nb_sec_AbCdEf... De publieke sleutel (nb_pub_*) identificeert de credential in onze logs + verschijnt in de NB-Credential-Id-header van webhook-afleveringen. Het secret authenticeert.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Scope-catalogus
Elke credential wordt aangemaakt met een expliciete scope-set. Verzoeken buiten die scopes retourneren 403. De scope-catalogus is vast (geen custom scopes in v1):
| Scope | Verleent |
|---|---|
sessions:read | Sessies opsommen + ophalen |
sessions:write | Sessies aanmaken + beëindigen |
participants:read | Deelnemers van een sessie opsommen |
participants:write | Veldgebruiker-uitnodigingen genereren |
evidence:read | Bewijsregels opsommen + ophalen + ondertekende download-URL's |
recordings:read | Metadata van opname-artefacten + download-URL's lezen |
audit:read | De audit-keten per sessie + TSA-ankercoördinaten lezen |
webhooks:read | Geregistreerde webhook-endpoints + afleveringslogboek opsommen |
webhooks:write | Webhook-endpoints registreren / geheim roteren / verwijderen |
branding:read | Org-branding lezen (logo / kleuren / PDF-footer) |
branding:write | Org-branding muteren |
org:read | Org-metadata lezen |
whiteboards:read | Whiteboards per sessie opsommen |
Rotatie
Om zonder downtime te roteren:
- Geef een nieuwe credential uit met dezelfde scope-set.
- Deploy het nieuwe secret naar uw applicatie.
- Verifieer dat de nieuwe credential verkeer verwerkt (Admin → API-credentials toont het last-used-tijdstempel).
- Soft-revoke de oude credential. Bestaande verzoeken die hem gebruiken geven 401; het audit-spoor van eerdere calls blijft intact.
Constante-tijd-verificatie
Op de backend worden secrets opgeslagen als SHA-256(secret + SECRET_KEY_pepper) en in constante tijd vergeleken (hmac.compare_digest). Een gelekte hash-dump kan niet naar de platte tekst worden gebrute-forced zonder ook de pepper te breken.
Wat deze credential NIET verleent
- SPA-admin-toegang — die is apart (operator-login + RBAC).
- Deelname aan veldkant — die gebruikt eenmalige ondertekende URL's, gegenereerd via
sessions.invite(). - SCIM-provisioning — gebruikt een apart bearer-token per org, zie SCIM-provisioning.
- Webhook-ondertekening — dat gebeurt met het
whsec_*-secret per endpoint, zie Webhooks.
Audit-spoor
Elke API-call wordt gelogd met de publieke sleutel van de credential + het endpoint + de status. Operaties die state muteren schrijven aanvullend auditrijen in de betrokken org. Admin kan de activiteit van de credential bekijken via Admin → API-credentials → [credential] → Activiteit.