Uwierzytelnianie
Każde żądanie do publicznego API niesie parę poświadczeń — nb_pub_* (klucz publiczny) + nb_sec_* (sekret). Sekret jest wysyłany jako token Bearer. Poświadczenie jest ograniczone do pojedynczej organizacji + stałego katalogu zakresów.
Wystawianie poświadczeń
- Zaloguj się do swojej organizacji na app.nexbasira.com.
- Przejdź do Admin → Poświadczenia API.
- Kliknij Wystaw poświadczenie, wybierz nazwę + zakresy, potwierdź.
- Skopiuj parę
nb_pub_*+nb_sec_*. Sekret jest pokazywany dokładnie raz. Zapisz go natychmiast w swoim menedżerze sekretów — po naszej stronie przechowujemy jedynie skrót SHA-256.
Używanie poświadczenia
Authorization: Bearer nb_sec_AbCdEf... Klucz publiczny (nb_pub_*) identyfikuje poświadczenie w naszych logach + pojawia się w nagłówku NB-Credential-Id dostarczeń webhooków. Sekret uwierzytelnia.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Katalog zakresów
Każde poświadczenie jest tworzone z jawnym zestawem zakresów. Żądania poza tymi zakresami zwracają 403. Katalog zakresów jest stały (brak niestandardowych zakresów w v1):
| Zakres | Uprawnienia |
|---|---|
sessions:read | Listowanie + pobieranie sesji |
sessions:write | Tworzenie sesji + ich kończenie |
participants:read | Listowanie uczestników sesji |
participants:write | Generowanie zaproszeń dla użytkowników terenowych |
evidence:read | Listowanie + pobieranie wierszy dowodów + podpisanych URL-i pobierania |
recordings:read | Odczyt metadanych artefaktów nagrań + URL-i pobierania |
audit:read | Odczyt łańcucha audytu per sesja + współrzędnych kotwicy TSA |
webhooks:read | Listowanie zarejestrowanych endpointów webhook + logu dostarczeń |
webhooks:write | Rejestrowanie / rotacja sekretu / usuwanie endpointów webhook |
branding:read | Odczyt brandingu organizacji (logo / kolory / stopka PDF) |
branding:write | Modyfikacja brandingu organizacji |
org:read | Odczyt metadanych organizacji |
whiteboards:read | Listowanie tablic per sesja |
Rotacja
Aby dokonać rotacji bez przestoju:
- Wystaw nowe poświadczenie z tym samym zestawem zakresów.
- Wdróż nowy sekret w swojej aplikacji.
- Zweryfikuj, że nowe poświadczenie obsługuje ruch (Admin → Poświadczenia API pokazuje znacznik czasu ostatniego użycia).
- Miękko unieważnij stare poświadczenie. Istniejące żądania z jego użyciem zwracają 401; ślad audytu dawnych wywołań pozostaje nienaruszony.
Weryfikacja w stałym czasie
Po stronie backendu sekrety są przechowywane jako SHA-256(secret + SECRET_KEY_pepper) i porównywane w stałym czasie (hmac.compare_digest). Wyciek zrzutu skrótów nie może zostać złamany brute-force do postaci jawnej bez jednoczesnego złamania peppera.
Czego to poświadczenie NIE nadaje
- Dostępu administracyjnego do SPA — to oddzielna kwestia (logowanie operatora + RBAC).
- Dołączania po stronie terenowej — używa ono jednorazowych podpisanych URL-i generowanych przez
sessions.invite(). - Provisioningu SCIM — używa oddzielnego tokenu bearer per organizacja, patrz Provisioning SCIM.
- Podpisywania webhooków — to realizowane sekretem
whsec_*per endpoint, patrz Webhooki.
Ślad audytu
Każde wywołanie API jest logowane wraz z kluczem publicznym poświadczenia + endpointem + statusem. Operacje zmieniające stan dodatkowo zapisują wiersze audytu w dotkniętej organizacji. Administrator może obejrzeć aktywność poświadczenia w Admin → Poświadczenia API → [poświadczenie] → Aktywność.