Uwierzytelnianie

API uwierzytelnia serwery za pomocą kluczy API organizacji. Klucz należy do organizacji (a nie do osoby), ma określony zestaw uprawnień i działa w dokładnie jednym trybie: testowym albo produkcyjnym.

Przesyłanie klucza

Użyj jednego z nagłówków:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Klucze mają postać bf_live_… lub bf_test_…. Brak klucza skutkuje odpowiedzią 401 (unauthorized); klucz nieprawidłowy, odwołany lub wygasły również daje 401. Przechowuj klucze na serwerze: nigdy nie umieszczaj ich w przeglądarce ani w aplikacji mobilnej. Do podpisywania w przeglądarce utwórz zamiast tego sesję podpisywania.

Klucze testowe i produkcyjne

	Testowy (`bf_test_…`)	Produkcyjny (`bf_live_…`)
Dokumenty	Renderowane ze znakiem wodnym `TEST`	Bez znaku wodnego
E-mail	Dostarczany tylko członkom Twojej organizacji	Dostarczany do każdego odbiorcy
Rozliczenia	Bezpłatnie i bez limitu, nigdy nie są liczone	Zakończone koperty wliczają się do Twojego planu
Dane	Koperty, linki i punkty końcowe webhooków utworzone kluczem są w trybie testowym	W trybie produkcyjnym

Tryb wynika z klucza, nigdy z żądania: ?test_mode=true w POST /v1/envelopes dotyczy tylko sesji panelu. Listy (GET /v1/envelopes, GET /v1/signing-links) zwracają wyłącznie elementy w trybie klucza, a zdarzenia koperty trafiają tylko do punktów końcowych webhooków w tym samym trybie. Każda koperta i każdy ładunek webhooka informuje, w jakim jest trybie (testMode).

Tworzenie i odwoływanie kluczy

Kluczami zarządza się w panelu, w sekcji Ustawienia › Klucze API; mogą to robić członkowie z uprawnieniem apikey:manage (właściciele i administratorzy). Sekret jest wyświetlany tylko raz, w chwili utworzenia klucza. Kluczowi można nadać nazwę, tryb, termin ważności (od 1 do 365 dni lub bezterminowo) i zakresy.

Zakresy

Zakresy klucza to uprawnienia organizacji, z których może korzystać. Domyślnie nowy klucz otrzymuje uprawnienia twórcy z wyjątkiem administracyjnych (org:manage, member:manage, sso:manage, apikey:manage, billing:manage) i nikt nie może nadać kluczowi uprawnienia, którego sam nie ma. Wywołanie spoza zakresów klucza kończy się błędem 403 ze wskazaniem brakującego uprawnienia:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Uprawnienie	Pozwala kluczowi
`template:read`	Wyświetlać i odczytywać szablony, wersje i ich pliki PDF
`template:write`	Tworzyć szablony, przesyłać pliki, zapisywać wersje robocze, usuwać nieużywane szablony
`template:publish`	Publikować wersję roboczą jako nową wersję
`envelope:read`	Wyświetlać i odczytywać koperty, dokumenty i ścieżki audytu; wyświetlać linki do podpisu
`envelope:send`	Tworzyć koperty, sesje podpisywania i linki do podpisu; ponownie wysyłać linki
`envelope:void`	Unieważniać koperty w toku
`org:manage`	Zarządzać punktami końcowymi webhooków i ponownie dostarczać zdarzenia; odczytywać ustawienia organizacji
`billing:manage`	Odczytywać użycie (`GET /v1/usage`) i kwoty faktur

Zarządzanie punktami końcowymi webhooków wymaga uprawnienia org:manage, którego klucze domyślnie nie dostają: rejestruj punkty końcowe w panelu albo jawnie utwórz klucz z tym zakresem.

Które punkty końcowe akceptują jakie poświadczenia

Każda operacja w dokumentacji API podaje swoje schematy zabezpieczeń. W skrócie:

Klucz API lub sesja panelu: szablony, koperty, sesje podpisywania, linki do podpisu, punkty końcowe webhooków, ustawienia organizacji, przegląd rozliczeń i użycie.
Tylko sesja panelu: klucze API, tokeny SCIM, ustawienia połączenia SSO, przesyłanie logo organizacji, płatność i portal rozliczeń, wyświetlanie sekretu webhooka.
Token osoby podpisującej: /v1/signing/*, używane przez hostowaną stronę i <bf-signing> z tokenem sesji (bfs_…) lub tokenem dostępu, na który jest on wymieniany (bfa_…).
Publiczne: /v1/links/{id} (stałe linki), /v1/sso/discover oraz API weryfikacji (/v1/public/*, /.well-known/bona-fide/keys.json).

Logowanie do panelu

Ludzie (nie serwery) logują się do panelu pod adresem https://app.bonafidesign.com/sign-in. Domyślnie służy do tego adres e-mail i hasło; alternatywy to sześciocyfrowy kod wysyłany e-mailem (Wyślij mi zamiast tego kod), magiczny link, klucz dostępu (passkey), Google lub Microsoft oraz SSO Twojej firmy.

Utworzenie konta z hasłem powoduje wysłanie jednej wiadomości e-mail: kodu potwierdzającego, że adres należy do Ciebie. Do tego czasu hasło nie pozwala się zalogować. Rejestracja z adresem, który ma już konto, niczego nie zmienia i daje dokładnie taką samą odpowiedź jak nowa rejestracja; właściciel adresu otrzymuje wiadomość z wyjaśnieniem, jak się zamiast tego zalogować.
Hasła mają od 12 do 128 znaków i są przechowywane jako solone skróty scrypt. Nowe hasło, które pojawiło się w znanym wycieku danych, jest odrzucane: do serwisu Have I Been Pwned wysyłanych jest tylko pierwszych pięć znaków jego skrótu SHA-1 (k-anonimowość), nigdy samo hasło. Jeśli serwis nie odpowie w ciągu dwóch sekund, hasło zostaje przyjęte bez sprawdzenia.
Nie pamiętasz hasła? Wiadomość resetująca zawiera link do strony, na której wybierasz nowe hasło. Link działa jeden raz, wygasa po godzinie, a jego użycie wylogowuje Cię na wszystkich urządzeniach.
Nie masz jeszcze hasła? Konta utworzone za pomocą kodu, linku, klucza dostępu lub Google / Microsoft nadal logują się w ten sposób i mogą dodać hasło w sekcji Ustawienia › Konto. Ustawienie pierwszego hasła wymaga zalogowania w ciągu ostatnich 15 minut (strona wysyła e-mailem kod, aby potwierdzić, że to Ty); zmiana hasła wymaga podania obecnego. Obie operacje wylogowują pozostałe sesje.
Błędy nigdy nie ujawniają kont: błędne hasło, nieznany adres i konto bez hasła dają tę samą odpowiedź, a żądanie resetu zawsze informuje, że wiadomość jest w drodze.
Limity żądań: logowanie hasłem, rejestracja i żądania resetu są ograniczane według adresu IP i adresu e-mail; po przekroczeniu limitu odpowiedzią jest 429, dopóki nie minie okno czasowe.
Firmowe SSO: gdy Twoja organizacja wymusza SSO, członkowie z jej domen e-mail logują się wyłącznie przez dostawcę tożsamości. Hasła, kody i magiczne linki są dla nich odrzucane; właściciele zachowują kod e-mail jako awaryjną metodę logowania.

Identyfikatory żądań

Każda odpowiedź zawiera nagłówek x-request-id, a każda treść błędu pole requestId. Możesz wysłać własny x-request-id (od 8 do 128 znaków z zakresu A-Z a-z 0-9 . _ -), aby powiązać logi; w przeciwnym razie API wygeneruje go samo. Podawaj go w kontakcie z pomocą techniczną.