Authentication

The Machine API accepts one bearer token per request. Pass it through getToken in createKortix. The SDK sends it as Authorization: Bearer <token>.

import { createKortix } from '@kortix/sdk';

const kortix = createKortix({
  backendUrl: 'https://machineapi.myapps.ai/v1',
  getToken: async () => process.env.MACHINE_API_KEY!,
});

backendUrl and getToken are required. The SDK caches nothing: it calls getToken on every request, so your app owns token storage and refresh.

Set clientSource to api, cli, desktop, mobile, or web when your host needs a separate source in the centralized audit log. The SDK sends it as the X-Kortix-Client header. Any other value is dropped. This value identifies the client surface. It does not change the authenticated actor or their permissions.

Personal access tokens

A personal access token (PAT) is the credential for the SDK, the CLI, and CI. Create one in the web app at Settings → API keys, in the Developer group. The key starts with mach_pat_ and shows only once, at creation. Store it as a secret.

Keys that start with kortix_pat_ are the same kind of credential and work everywhere a mach_pat_ key does. You get one from machine login, and every key made before the mach_pat_ prefix existed has it.

To mint a key from code, call createAccountToken. Pass machinePrefix: true for a mach_pat_ key; without it the key starts with kortix_pat_. The plaintext key is in secret_key and is returned only once.

import { createAccountToken } from '@kortix/sdk';

const { secret_key } = await createAccountToken({
  name: 'ci',
  projectId, // omit for an account-wide key
  machinePrefix: true,
});

A PAT acts as the user who created it. Its scope is fixed at creation:

Choose the project scope for CI and other narrow-purpose credentials. machine login mints a PAT and stores it locally — it is the same credential type, not a separate token kind.

Service accounts

A service account is a separate credential family for non-human callers, prefixed kortix_sa_. It acts on its own, not as you, and keeps working after you leave the team. Create one at Settings → API keys: select Create key, then set Who uses it to An automation. Setting it to You and your own tools makes a personal access token instead.

Supabase JWT

If your app uses Machine's own sign-in, return the live session token instead of a PAT:

getToken: async () =>
  (await supabase.auth.getSession()).data.session?.access_token ?? null,

The SDK calls getToken on every request, so a refreshed token takes effect automatically.

Choose a credential