Authentication
Two concepts only — an API key (account-wide or project-scoped) for anything programmatic, or a Supabase JWT for web apps.
Kortix has exactly two ways to authenticate: a session (you logged in) and an
API key (everything programmatic — the SDK, the CLI, your backend, CI). The SDK
takes one via getToken, which it sends as Authorization: Bearer <token>.
API key — the one programmatic credential
Create one in Settings → API keys → Create key. Name it, choose its scope, copy it once (shown only at creation), and store it as a secret. An API key acts as you, so it can reach every project your account can.
Don't use a Service account here. Service accounts (kortix_sa_…) are a
separate, advanced IAM principal with no project access until it's explicitly
granted — point the SDK at one and every call returns 403 "You do not have access to this project". For the SDK, the CLI, and the white-label demo, you
want an API key from Settings → API keys.
const kortix = createKortix({
backendUrl: 'https://api.kortix.com/v1',
getToken: async () => process.env.KORTIX_API_KEY!,
});Scope — account-wide or one project
Scope is a property of the key, picked at creation:
| scope | the key can touch | use it for |
|---|---|---|
| Account (default) | every project in your account | a backend managing your workspace |
| Project | exactly one project — 403 everywhere else | CI/CD bound to one repo (least privilege) |
Pick the narrowest scope that does the job. Rotate by creating a new key and revoking the old one.
The CLI mints an API key for you — kortix login runs the browser authorize
flow and stores the key locally. Same credential, nothing special — there's no
separate "CLI token."
Supabase JWT — web apps on Kortix login
Only if you're building a web app on Kortix's own auth. Return the user's live
session token; it refreshes itself, so getToken re-reads it each call:
getToken: async () =>
(await supabase.auth.getSession()).data.session?.access_token ?? null,Which one?
| you're building | use |
|---|---|
| a backend, script, or CI | an API key (account-wide, or project-scoped for CI) |
| the Kortix CLI | kortix login (mints an API key for you) |
| a web app on Kortix login | a Supabase JWT |
API keys are bearer credentials — treat them like passwords. Keep them in a secret
manager, never in client-side code or a committed file. getToken is called on
demand, so the host owns storage, caching, and rotation.