Authenticate your API requests

The public /v1 API and the official SDK authenticate with a single, organization-scoped secret: an API key shaped like sk-live-.... You send it as a Bearer token on every request, and Qalyb resolves the key to the owning workspace (organization) before doing any work. There are no per-endpoint tokens and no OAuth dance for server-to-server calls.

The API key model

An API key belongs to one workspace (the sign-up wizard says "workspace"; the API calls it an organization). When you authenticate with a key, every agent, call, voice, and Models request is scoped to that workspace. Keys have these properties:

• Format. Keys look like sk-live-<random>. The sk-live- prefix is a label only — there is no separate test/live environment behind it.
• Stored hashed. Qalyb keeps only a SHA-256 hash of the key plus a short visible prefix (for example sk-live-XXXXXXXX…). The full secret is shown exactly once, at creation. If you lose it, mint a new one.
• Admin-equivalent. A key authenticates as an organization admin, so it can read and write the full set of workspace resources exposed by /v1.
• Revocable. Keys are revoked (soft-deactivated), not deleted. A revoked key stops working immediately and cannot be reactivated — issue a fresh one.
• Usage-tracked. Each authenticated request stamps the key's "last used" timestamp, so you can spot keys that are no longer in service.

Create a key

API keys are created, listed, and revoked by a workspace admin from the API Keys screen in your workspace settings. The screen shows each key's name, masked prefix, created date, and last-used date.

Authenticate a request

Send your key in the Authorization header as a Bearer token on every /v1 request:

Authorization: Bearer sk-live-...

That is the whole protocol. A simple authenticated call — list the agents in your workspace — looks like this:

curl https://api.qalyb.ai/v1/agents \
  -H "Authorization: Bearer sk-live-..."

The fastest way to confirm a key is valid is GET /v1/me, which introspects the credential and tells you which workspace it resolves to:

curl https://api.qalyb.ai/v1/me \
  -H "Authorization: Bearer sk-live-..."

A valid key returns the authenticated identity and organization:

{
  "authenticated": true,
  "authType": "api_key",
  "organizationId": "org_8f1c...",
  "user": {
    "id": "usr_2b9a...",
    "email": "ops@acme.sa"
  }
}

An invalid or missing key returns 401 Unauthorized:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

Use the key with the SDK

The TypeScript SDK accepts your key once at construction and attaches the Authorization header to every request automatically:

import { Qalyb } from '@qalyb/sdk';

const qalyb = new Qalyb({
  apiKey: process.env.QALYB_API_KEY!, // sk-live-...
});

// Every call now sends Authorization: Bearer <apiKey> for you.
const agents = await qalyb.agents.list();

What a key can access (scopes)

Qalyb does not (yet) issue narrowly scoped keys. Because a key authenticates as an organization admin, it can reach every resource the /v1 API exposes for its workspace:

In-app session auth

There is a second way /v1 routes can be authenticated, used by the dashboard itself before a user has minted a key: a signed-in browser session token paired with an x-organization-id header. This path exists for the dashboard — for any server-to-server integration you write, use an sk-live-... API key. (One nuance: GET /v1/me also accepts the browser session cookie, which is how the documentation site detects whether you are signed in.)

Usage metering and limits

Authentication and billing are linked. Every successful Models call — TTS, STT, and LLM chat — is metered against your workspace's usage credits the moment it succeeds:

Models requests are also logged per workspace — method, endpoint, model, latency, status, and the characters / seconds / tokens consumed — so you can audit exactly what each key did. Agent, call, and identity (/v1/me) routes are not metered as Models usage.

Rotate and revoke keys

Because the full secret is only ever shown once, key rotation is a create-then-revoke operation rather than an in-place reset:

1. Create a new key with a descriptive name (for example Production API 2026-Q3).
2. Deploy the new key to your servers and confirm traffic flows.
3. Revoke the old key from the API Keys screen.

Use the per-key last used timestamp to confirm a retired key really has gone quiet before you revoke it.