Hitelesítés

API-kulcsok (integrációkhoz ajánlott)

Az API-kulcs egy személyes hozzáférési token, amely a fiókod egy tagjához kötődik.

• Létrehozás a Beállítások → Pluginek → RolChat API-kulcsok menüben. A titkos kulcs egyszer jelenik meg; ezután csak az első tíz karaktere látható, a RolChat pedig csak SHA-256 hash-t tárol.
• Formátum: rcp_, majd 32 véletlen bájt base64url kódolásban, összesen körülbelül 45 karakter. Az előtag felismerhetővé teszi a kulcsot a naplókban, és megkülönbözteti a munkamenet-tokentől.
• Hatókörök: a kulcs létrehozásakor egy rögzített képességkatalógusból választhatók. Egy kulcs soha nem tehet többet, mint az a tag, aki létrehozta: minden hívásnál mindkét feltételt ellenőrizzük, a képesség szerepel a kulcs hatókörei között, és a tag még rendelkezik vele. Ha szűkíted a tag szerepkörét, a kulcs is vele együtt szűkül.
• Élettartam: a kulcsok maguktól nem járnak le. Egy kulcsot a profiloldalon vagy a DELETE /api/v1/tokens/:id hívással vonhatsz vissza; a visszavonás azonnal érvénybe lép. Helyben történő cserére nincs lehetőség: vond vissza, és hozz létre új kulcsot.
• A létrehozás és a visszavonás bekerül az auditnaplóba.

Bearer tokenként küldd - külön API-kulcs fejléc nincs:

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

A plugin API-kulccsal küldött kérések percenként 300-ra korlátozottak.

JWT-munkamenetek

A webalkalmazás és a mobil SDK-k e-mail-címmel és jelszóval (vagy Google- vagy Apple-fiókkal) jelentkeznek be, és tokenpárt kapnak.

Token	Élettartam	Megjegyzések
Hozzáférési token	15 perc	RS256, a /.well-known/jwks.json címen található JWKS alapján ellenőrizve
Frissítési token	30 nap	Minden frissítéskor cserélődik; egy lecserélt token újrafelhasználása a teljes láncot visszavonja

Claimek: sub (felhasználó), acc (fiók), rl (szerepkör), valamint webhelyenkénti szerepkörök esetén sts (engedélyezett webhelyek).

A POST /auth/login, a /auth/refresh, a /auth/swap-company és a /auth/logout az egyetlen hitelesítési folyamatbeli végpont, amely nem tartalmazhatja a következőkben leírt X-Account-Id fejlécet.

Az X-Account-Id fejléc

A fenti négy kivételével minden hitelesített kérésnek tartalmaznia kell azt a fiókot, amelyen a művelet történik:

X-Account-Id: <account uuid>

A szerver ellenőrzi, hogy a fejléc megegyezik-e a token acc claimjével (vagy az API-kulcs fiókjával). Hiányzó fejléc esetén 400 missing_required_header, eltérés esetén 403 account_context_mismatch a válasz. A fejléc azért létezik, hogy egy klienshiba vagy egy visszajátszott token soha ne olvashassa csendben egy másik bérlő adatait: az eltérést bármely lekérdezés futása előtt elutasítjuk, és minden naplósor a token dekódolása nélkül is egy fiókhoz rendelhető.

Több céghez tartozó felhasználók

Egy személy több céghez is tartozhat. Minden cégnek saját tokenje van (saját acc claimmel). Váltás:

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

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

A célnak a hívó available_companies listájában (a bejelentkezéskor visszaadva) kell szerepelnie, különben 403 forbidden a válasz. A válasz egy új, a célra korlátozott hozzáférési és frissítési tokenpár; a régi frissítési token visszavonásra kerül, és egy auth.account.swapped auditesemény íródik.

Többtényezős hitelesítés

A TOTP-alapú MFA tagonként beállítható, és fiókonként kötelezővé tehető. Bekapcsolt állapotban a POST /auth/login egy kihívást ad vissza, a munkamenet pedig a POST /auth/mfa/verify hívással fejeződik be. A tartalékkódokat a beállításkor adjuk ki.

Bejelentkezési védelem

• A bejelentkezési útvonalak IP-címenként percenként 10, e-mail-címenként 15 percenként 5 kísérletre korlátozottak.
• Tíz sikertelen bejelentkezés 30 percre zárolja az e-mail-címet; a válasz code: account_locked értéket tartalmaz.
• A reCAPTCHA műveletenként bekapcsolható (regisztráció, bejelentkezés, jelszó-visszaállítás); a nyilvános indítási konfigurációt a GET /api/v1/captcha szolgálja ki.