Authentication

Trueyy uses two kinds of credentials: a master API key that lives only on your backend, and short-lived session tokens that your backend mints for the browser.

Master API key

Your backend authenticates to the Trueyy API with a master key on the Authorization header:

Authorization: Bearer tk_live_...

The @trueyy-sdk/node client handles this for you - you just pass the key when you construct it:

import { Trueyy } from "@trueyy-sdk/node";

const trueyy = new Trueyy({
  apiKey: process.env.TRUEYY_API_KEY!,   // tk_live_ or tk_test_
});

tk_live_... - production key.
tk_test_... - sandbox key.

Never expose the master key

The tk_live_ key can create interviews, mint tokens, and read reports across your whole account. Keep it server-side only - never ship it to the browser, a mobile app, or a public repo. The browser gets short-lived session tokens instead (below).

Getting a key

Generate one in the dashboard at app.trueyy.com → Settings → API Tokens.

Plan requirements

SDK and API access is gated by plan. It's included on:

Growth (monthly or yearly)
Starter - annual only
Enterprise

If you don't see the API Tokens option in Settings, your current plan doesn't include SDK access yet. Upgrade in the dashboard, or contact us to enable it.

Access is checked continuously

SDK access is verified both when a token is minted and on every API request. If a plan is downgraded so it no longer includes SDK access, existing keys stop working immediately.

Session tokens (browser)

Your frontend never holds the master key. Instead, your backend mints a short-lived (5-minute) JWT scoped to a single round and role, and hands that to the browser:

const { token, expires_at, role } = await trueyy.tokens.mint(
  round_id,
  "candidate"   // "candidate" | "interviewer" | "helper"
);

The frontend passes this token to <TrueyyProvider>. Because it's short-lived and single-session, the blast radius of a leaked browser token is one session for five minutes.

Refreshing tokens

Tokens expire after ~5 minutes. The browser client detects this ~30 seconds before expiry and calls your onTokenExpiring handler, which should fetch a fresh token from your backend:

<TrueyyProvider
  token={sessionJwt}
  onTokenExpiring={async () => {
    const res = await fetch("/our-ats/refresh-trueyy-token");
    return res.text();   // your backend calls trueyy.tokens.mint(round_id, role)
  }}
>

See Architecture for the full token-flow diagram.

Configuration reference

new Trueyy({
  apiKey: string,             // REQUIRED - tk_live_ or tk_test_
  baseUrl?: string,           // default: "https://api.trueyy.com"
  timeout?: number,           // default: 10_000 (ms)
  fetchImpl?: typeof fetch,   // default: globalThis.fetch
});

Override baseUrl only if you're pointing at a custom Trueyy endpoint. Override fetchImpl to inject a polyfill or instrumentation (e.g. undici, an OpenTelemetry-wrapped fetch).