Authentifizierung
Jeder Request an die öffentliche API trägt ein Credential-Paar — nb_pub_* (Public Key) + nb_sec_* (Secret). Das Secret wird als Bearer-Token gesendet. Das Credential ist auf eine einzige Org + einen festen Scope-Katalog beschränkt.
Credentials ausstellen
- Melden Sie sich bei Ihrer Org unter app.nexbasira.com an.
- Gehen Sie zu Admin → API-Credentials.
- Klicken Sie auf Credential ausstellen, wählen Sie einen Namen + Scopes, bestätigen Sie.
- Kopieren Sie das
nb_pub_*- +nb_sec_*-Paar. Das Secret wird genau einmal angezeigt. Speichern Sie es sofort in Ihrem Secrets-Manager — wir behalten nur einen SHA-256-Hash auf unserer Seite.
Das Credential verwenden
Authorization: Bearer nb_sec_AbCdEf... Der Public Key (nb_pub_*) identifiziert das Credential in unseren Logs + erscheint im NB-Credential-Id-Header der Webhook-Zustellungen. Das Secret authentifiziert.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Scope-Katalog
Jedes Credential wird mit einem expliziten Scope-Set erstellt. Requests außerhalb dieser Scopes geben 403 zurück. Der Scope-Katalog ist fest (keine benutzerdefinierten Scopes in v1):
| Scope | Gewährt |
|---|---|
sessions:read | Sessions auflisten + abrufen |
sessions:write | Sessions erstellen + beenden |
participants:read | Teilnehmer einer Sitzung auflisten |
participants:write | Feldbenutzer-Einladungen prägen |
evidence:read | Evidence-Zeilen + signierte Download-URLs auflisten + abrufen |
recordings:read | Metadaten von Aufzeichnungs-Artefakten + Download-URLs lesen |
audit:read | Die sitzungsbezogene Audit-Kette + TSA-Anker-Koordinaten lesen |
webhooks:read | Registrierte Webhook-Endpoints + Zustellungsprotokoll auflisten |
webhooks:write | Webhook-Endpoints registrieren / Secret rotieren / löschen |
branding:read | Org-Branding lesen (Logo / Farben / PDF-Footer) |
branding:write | Org-Branding mutieren |
org:read | Org-Metadaten lesen |
whiteboards:read | Whiteboards pro Sitzung auflisten |
Rotation
So rotieren Sie ohne Ausfallzeit:
- Stellen Sie ein neues Credential mit demselben Scope-Set aus.
- Deployen Sie das neue Secret in Ihre Anwendung.
- Verifizieren Sie, dass das neue Credential Traffic übernimmt (Admin → API-Credentials zeigt den Last-Used-Zeitstempel).
- Widerrufen Sie das alte Credential sanft. Bestehende Requests damit erhalten 401; der Audit-Trail vergangener Calls bleibt intakt.
Konstantzeit-Verifizierung
Auf dem Backend werden Secrets als SHA-256(secret + SECRET_KEY_pepper) gespeichert und in konstanter Zeit verglichen (hmac.compare_digest). Ein geleakter Hash-Dump kann ohne gleichzeitigen Bruch des Peppers nicht per Brute-Force in den Klartext zurückgeführt werden.
Was dieses Credential NICHT gewährt
- SPA-Verwaltungszugriff — der ist getrennt (Operator-Login + RBAC).
- Feldseitiger Beitritt — der nutzt einmalig signierte URLs, geprägt via
sessions.invite(). - SCIM-Provisionierung — nutzt ein separates organisationsspezifisches Bearer-Token, siehe SCIM-Provisionierung.
- Webhook-Signierung — die erfolgt mit dem endpoint-spezifischen
whsec_*-Secret, siehe Webhooks.
Audit-Trail
Jeder API-Call wird mit dem Public Key des Credentials + dem Endpoint + Status protokolliert. Zustandsverändernde Operationen schreiben zusätzlich Audit-Zeilen in die betroffene Org. Der Admin kann die Aktivität des Credentials unter Admin → API-Credentials → [Credential] → Aktivität einsehen.