Architecture
How tokens flow between your app, your backend, and Trueyy Cloud - and why it's secure.
The Trueyy SDK is built around one principle: your master API key never reaches the browser. Your backend mints short-lived, single-session tokens and hands those to the frontend.
Token flow
- Your frontend asks your backend to schedule / start a round.
- Your backend (holding
tk_live_) calls the Trueyy API and mints one short-lived JWT per role. - Your backend returns those JWTs to the frontend.
<TrueyyProvider>opens an authenticated WebSocket to Trueyy Cloud using the session JWT.
Why this is safe
Master key stays server-side
tk_live_ never leaves your backend. It's the only credential that can act across your whole account.
Small blast radius
A leaked browser JWT is scoped to one session and expires in ~5 minutes.
Auto-rotation
The browser client refreshes the JWT before expiry via your onTokenExpiring handler, then reconnects under the new auth.
The three roles
Every session token is minted for exactly one role:
| Role | Who holds it | What it's for |
|---|---|---|
candidate | The candidate's browser | The pre-join flow (<TrueyyJoin>) and consent. |
interviewer | The interviewer's browser | Live monitoring (<TrueyyMonitor>) and imperative commands. |
helper | The candidate's local capture helper | Captures signals the browser can't on the candidate's machine. |
The helper token is minted the same way as the others; the frontend hands it off during the candidate join flow. See Join & consent.
Consent is enforced server-side
Candidate monitoring is hard-gated on consent: no candidate data is captured for a session until consent is granted - this is a compliance guarantee (GDPR Art. 7), not just a UI nicety. The <TrueyyJoin> component ships a compliant, versioned consent flow out of the box. See Join & consent.