Authentication

Mga API key (inirerekomenda para sa mga integrasyon)

Ang API key ay personal access token na nakakabit sa isang miyembro ng account mo.

• Gumawa nito sa Mga Setting → Mga Plugin → Mga API key ng RolChat. Isang beses lang ipinapakita ang secret; pagkatapos, ang unang sampung character lang nito ang nakikita, at SHA-256 hash lang ang iniimbak ng RolChat.
• Format: rcp_ na sinusundan ng 32 random na byte sa base64url, mga 45 character lahat-lahat. Dahil sa prefix, nakikilala ang key sa mga log at naiiba ito sa session token.
• Mga scope: pinipili mula sa nakapirming katalogo ng mga kakayahan kapag ginagawa ang key. Hindi kailanman makakagawa ang key nang higit sa miyembrong gumawa nito: sa bawat tawag, sinusuri ang dalawang kondisyon, nasa mga scope ng key ang kakayahan at hawak pa rin ito ng miyembro. Paliitin ang role ng miyembro at kasabay na liliit ang key.
• Tagal ng bisa: hindi kusang nag-e-expire ang mga key. I-revoke ang key mula sa pahina ng profile o gamit ang DELETE /api/v1/tokens/:id; agad na umiiral ang pag-revoke. Walang in-place na rotation: i-revoke at gumawa ng bagong key.
• Isinusulat sa audit log ang paggawa at pag-revoke.

Ipadala ito bilang bearer token - walang hiwalay na header para sa API key:

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

Limitado sa 300 kada minuto ang mga request na may plugin API key.

Mga JWT session

Nagsa-sign in ang web app at ang mga mobile SDK gamit ang e-mail at password (o Google o Apple) at tumatanggap ng pares ng token.

Token	Tagal ng bisa	Mga tala
Access token	15 minuto	RS256, bine-verify laban sa JWKS sa /.well-known/jwks.json
Refresh token	30 araw	Nire-rotate sa bawat refresh; ang muling paggamit ng na-rotate na token ay nagre-revoke sa buong chain

Mga claim: sub (user), acc (account), rl (role) at, para sa mga role kada site, sts (mga pinapayagang site).

Ang POST /auth/login, /auth/refresh, /auth/swap-company at /auth/logout lang ang mga endpoint ng authenticated flow na hindi dapat magdala ng header na X-Account-Id na inilalarawan sa susunod.

Ang header na X-Account-Id

Dapat dalhin ng bawat authenticated na request, maliban sa apat sa itaas, ang account na pinagtatrabahuhan nito:

X-Account-Id: <account uuid>

Sinusuri ng server na katumbas ng header ang claim na acc ng token (o ang account ng API key). Ang nawawalang header ay 400 missing_required_header; ang hindi pagtutugma ay 403 account_context_mismatch. Umiiral ang header para hindi kailanman tahimik na makabasa ng data ng ibang tenant ang bug sa client o ang na-replay na token: tinatanggihan ang hindi pagtutugma bago tumakbo ang anumang query, at maiuugnay sa isang account ang bawat log line nang hindi dine-decode ang token.

Mga user na may maraming kumpanya

Puwedeng kabilang ang isang tao sa ilang kumpanya. May sariling token ang bawat kumpanya (sariling claim na acc). Para lumipat:

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

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

Dapat kabilang ang target sa available_companies ng tumatawag (ibinabalik sa login), kung hindi ay 403 forbidden. Ang sagot ay bagong pares ng access at refresh token na naka-scope sa target; nire-revoke ang lumang refresh token at isinusulat ang audit event na auth.account.swapped.

Multi-factor authentication

Puwedeng i-enroll ang MFA na batay sa TOTP kada miyembro at gawing required kada account. Kapag naka-on ito, nagbabalik ang POST /auth/login ng challenge at nakukumpleto ang session gamit ang POST /auth/mfa/verify. Ibinibigay ang mga backup code sa enrollment.

Proteksyon sa pag-sign in

• Limitado ang mga ruta ng pag-sign in sa 10 pagtatangka kada IP kada minuto at 5 kada e-mail kada 15 minuto.
• Sampung bigong pag-sign in ang nagla-lock sa e-mail nang 30 minuto; dala ng sagot ang code: account_locked.
• Puwedeng i-enable ang reCAPTCHA kada aksyon (pag-sign up, pag-sign in, pag-reset ng password); ibinibigay ang pampublikong bootstrap configuration mula sa GET /api/v1/captcha.