Authentication

Koltrix has two authentication methods:

Surface	Auth
`app.koltrix.com` (dashboard)	Clerk session (sign-in form, magic link, SSO)
`/api/v1/*`	Clerk JWT (issued by the dashboard, one per logged-in user)
`/api/v2/*`	API key Bearer token (`kx_…`)
SMTP relay :2525	SMTP AUTH PLAIN/LOGIN where password = your `kx_` key

API keys

Create one in Settings → API Keys. Each key is scoped to a single organisation and one or more permission scopes:

read — list and read resources
send — send transactional email (REST + SMTP)
newsletter — manage lists and subscribers
contacts — manage CRM contacts

Keys are SHA-256 hashed at rest. We show the full secret exactly once — store it somewhere safe, we cannot recover it.

curl https://api.koltrix.com/api/v2/me \
  -H "Authorization: Bearer kx_..."

{ "tenant": "acme", "permissions": ["read", "send", "newsletter"] }

Revoking keys

DELETE /api/v1/api-keys/{id} (called by the dashboard) sets revoked_at. Subsequent requests with that key return 401. Anything in flight finishes without interruption.

Multi-organisation users

If a user belongs to several Clerk organisations, the dashboard ships with an org switcher in the sidebar. Switching changes the Clerk active org, which makes every subsequent JWT include the new org_id — and so the tenant middleware switches the database search_path for that request.

Rate limits

Per-IP: 300 requests/minute (sliding window, Redis-backed). Returns 429 too many requests.
Per-key (v2) / per-user (v1): 60 / minute by default.
Idempotency-Key replays don't count toward your quota.

Raise it for active accounts by contacting us.