Todennus

API-avaimet (suositellaan integraatioihin)

API-avain on henkilökohtainen käyttötunniste, joka on sidottu tilisi jäseneen.

• Luo avain kohdassa Asetukset → Laajennukset → RolChat API -avaimet. Salaisuus näytetään kerran; sen jälkeen näkyvissä ovat vain sen kymmenen ensimmäistä merkkiä, ja RolChat tallentaa vain SHA-256-tiivisteen.
• Muoto: rcp_ ja sen perässä 32 satunnaista tavua base64url-muodossa, yhteensä noin 45 merkkiä. Etuliitteen ansiosta avaimen tunnistaa lokeista ja sen erottaa istuntotunnisteesta.
• Oikeusalueet: valitaan kiinteästä kyvykkyysluettelosta avainta luotaessa. Avain ei voi koskaan tehdä enempää kuin sen luonut jäsen: jokaisessa kutsussa tarkistetaan molemmat ehdot, kyvykkyys on avaimen oikeusalueissa ja jäsenellä on se edelleen. Kun jäsenen roolia kavennetaan, avain kapenee sen mukana.
• Kesto: avaimet eivät vanhene itsestään. Peru avain profiilisivulta tai kutsulla DELETE /api/v1/tokens/:id; peruutus tulee voimaan välittömästi. Paikallaan kierrättämistä ei ole: peru avain ja luo uusi.
• Luonti ja peruutus kirjataan tarkastuslokiin.

Lähetä avain bearer-tunnisteena - erillistä API-avainotsaketta ei ole:

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

Laajennuksen API-avaimella tehdyt pyynnöt on rajoitettu 300:aan minuutissa.

JWT-istunnot

Verkkosovellus ja mobiili-SDK:t kirjautuvat sähköpostilla ja salasanalla (tai Googlella tai Applella) ja saavat tunnisteparin.

Tunniste	Kesto	Huomautukset
Käyttötunniste (access token)	15 minuuttia	RS256, tarkistetaan JWKS:ää vasten osoitteessa /.well-known/jwks.json
Päivitystunniste (refresh token)	30 päivää	Kierrätetään jokaisella päivityksellä; kierrätetyn tunnisteen uudelleenkäyttö mitätöi koko ketjun

Väitteet (claims): sub (käyttäjä), acc (tili), rl (rooli) ja sivustokohtaisille rooleille sts (sallitut sivustot).

POST /auth/login, /auth/refresh, /auth/swap-company ja /auth/logout ovat ainoat todennusvirran päätepisteet, joissa ei saa olla seuraavaksi kuvattua X-Account-Id-otsaketta.

X-Account-Id-otsake

Jokaisessa todennetussa pyynnössä yllä mainittuja neljää lukuun ottamatta on oltava tili, jonka puolesta toimitaan:

X-Account-Id: <account uuid>

Palvelin tarkistaa, että otsake vastaa tunnisteen acc-väitettä (tai API-avaimen tiliä). Puuttuva otsake on 400 missing_required_header; ristiriita on 403 account_context_mismatch. Otsake on olemassa, jotta asiakasohjelman virhe tai toistettu tunniste ei voi koskaan lukea toisen vuokralaisen tietoja huomaamatta: ristiriita hylätään ennen kuin yhtään kyselyä suoritetaan, ja jokainen lokirivi voidaan kohdistaa tiliin purkamatta tunnistetta.

Usean yrityksen käyttäjät

Yksi henkilö voi kuulua useaan yritykseen. Jokaisella yrityksellä on oma tunnisteensa (oma acc-väite). Vaihtaminen:

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

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

Kohteen on oltava yksi kutsujan available_companies-yrityksistä (palautetaan kirjautumisen yhteydessä), muuten 403 forbidden. Vastaus on uusi käyttö- ja päivitystunnistepari, joka on rajattu kohteeseen; vanha päivitystunniste mitätöidään ja kirjoitetaan tarkastustapahtuma auth.account.swapped.

Monivaiheinen tunnistautuminen

TOTP-pohjaisen monivaiheisen tunnistautumisen voi ottaa käyttöön jäsenkohtaisesti ja vaatia tilikohtaisesti. Kun se on käytössä, POST /auth/login palauttaa haasteen, ja istunto viimeistellään kutsulla POST /auth/mfa/verify. Varakoodit myönnetään käyttöönoton yhteydessä.

Kirjautumisen suojaus

• Kirjautumisreitit on rajoitettu 10 yritykseen IP-osoitetta kohden minuutissa ja 5 yritykseen sähköpostia kohden 15 minuutissa.
• Kymmenen epäonnistunutta kirjautumista lukitsee sähköpostiosoitteen 30 minuutiksi; vastauksessa on code: account_locked.
• reCAPTCHA voidaan ottaa käyttöön toimintokohtaisesti (rekisteröityminen, kirjautuminen, salasanan palautus); julkinen alustuskonfiguraatio toimitetaan osoitteesta GET /api/v1/captcha.