Uwierzytelnianie

Klucze API (zalecane dla integracji)

Klucz API to osobisty token dostępu powiązany z członkiem Twojego konta.

Utwórz go w Ustawienia → Wtyczki → Klucze API RolChat. Sekret jest pokazywany raz; później widać tylko jego pierwsze dziesięć znaków, a RolChat przechowuje wyłącznie skrót SHA-256.
Format: rcp_, a po nim 32 losowe bajty w base64url, łącznie około 45 znaków. Prefiks sprawia, że klucz łatwo rozpoznać w logach i odróżnić od tokenu sesji.
Zakresy: wybierane przy tworzeniu klucza ze stałego katalogu uprawnień. Klucz nigdy nie może więcej niż członek, który go utworzył: przy każdym wywołaniu sprawdzane są oba warunki, czyli uprawnienie jest w zakresach klucza i członek nadal je posiada. Zawęź rolę członka, a klucz zawęzi się razem z nią.
Czas życia: klucze nie wygasają same. Odwołaj klucz na stronie profilu lub przez DELETE /api/v1/tokens/:id; odwołanie działa natychmiast. Nie ma rotacji w miejscu: odwołaj klucz i utwórz nowy.
Utworzenie i odwołanie są zapisywane w dzienniku audytu.

Wysyłaj go jako token bearer - nie ma osobnego nagłówka dla klucza API:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Żądania z kluczem API wtyczki są ograniczone do 300 na minutę.

Sesje JWT

Aplikacja webowa i mobilne SDK logują się e-mailem i hasłem (albo przez Google lub Apple) i otrzymują parę tokenów.

Token	Czas życia	Uwagi
Token dostępu	15 minut	RS256, weryfikowany względem JWKS pod `/.well-known/jwks.json`
Token odświeżania	30 dni	Wymieniany przy każdym odświeżeniu; ponowne użycie wymienionego tokenu unieważnia cały łańcuch

Claimy: sub (użytkownik), acc (konto), rl (rola) oraz, dla ról przypisanych do stron, sts (dozwolone strony).

POST /auth/login, /auth/refresh, /auth/swap-company i /auth/logout to jedyne endpointy przepływu uwierzytelniania, które nie mogą zawierać opisanego dalej nagłówka X-Account-Id.

Nagłówek `X-Account-Id`

Każde uwierzytelnione żądanie poza czterema powyższymi musi wskazywać konto, w którego imieniu działa:

X-Account-Id: <account uuid>

Serwer sprawdza, czy nagłówek jest równy claimowi acc tokenu (lub kontu klucza API). Brak nagłówka to 400 missing_required_header; niezgodność to 403 account_context_mismatch. Nagłówek istnieje po to, aby błąd klienta albo odtworzony token nigdy nie mógł po cichu odczytać danych innego najemcy: niezgodność jest odrzucana, zanim wykona się jakiekolwiek zapytanie, a każdy wpis w logu da się przypisać do konta bez dekodowania tokenu.

Użytkownicy wielu firm

Jedna osoba może należeć do kilku firm. Każda firma ma własny token (własny claim acc). Aby się przełączyć:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Firma docelowa musi być jedną z available_companies wywołującego (zwracanych przy logowaniu), w przeciwnym razie odpowiedź to 403 forbidden. Odpowiedź zawiera nową parę tokenów dostępu i odświeżania dla firmy docelowej; stary token odświeżania zostaje unieważniony, a w audycie zapisuje się zdarzenie auth.account.swapped.