Authentication

The API supports two authentication methods. Use API keys for server-to-server integrations; use session cookies when calling from the application UI.

API key authentication

API keys are the recommended method for third-party integrations.

Generate a key

1. Sign in to the dashboard.
2. Open Dashboard → API keys.
3. Click Generate key and give it a descriptive name (e.g. "Zapier", "Internal CRM sync").
4. Optionally set an expiration date.
5. Copy the key immediately — it is shown once and never again. The server only stores a SHA-256 hash plus the 12-character prefix.

Use the key

Send the key as a Bearer token:

Authorization: Bearer tke_live_aB3dE5gH7jK9mN1pQ3rS5tU7vW9xY1zA

Key format

tke_<environment>_<22-char base64url>

Lifecycle

Security checklist

• Never commit keys to source control or ship them to clients.
• Store in environment variables or a secret manager.
• Set expiry dates for time-bounded integrations.
• Revoke immediately if exposed.
• Rotate periodically — generate a new key, deploy, then revoke the old one.
• Use a separate key per integration so revoking one doesn't break the others.

See API keys endpoints for programmatic management.

Session authentication

Used implicitly when the application UI calls the API. Sessions are managed by better-auth via secure HTTP-only cookies.

Flow

1. User signs in at /login.
2. Server sets the session cookie.
3. Subsequent requests from the same browser carry the cookie automatically.
4. Sessions expire after the configured window (see better-auth config).

When to use

• First-party web app calls.
• Browser-side interactive flows.

For anything else — including any server-side code outside the Next.js app — use an API key.

Rate limiting

Both methods share the same per-principal quota.

See Rate limits for headers and backoff guidance.