Authentication
Your code authenticates to Koltrix with an API key. The same key works for
the REST API (https://api.koltrix.com/api/v2) and, with the send scope, as
the password for the SMTP relay.
| Surface | How it authenticates |
|---|---|
REST API, /api/v2/* | Authorization: Bearer kx_… |
| SMTP relay, port 2525 | AUTH PLAIN or AUTH LOGIN, the API key as the password |
| AI assistants (MCP) | OAuth sign-in with your Koltrix account, never an API key. See AI assistants. |
| The Koltrix app | Your account sign-in, in the browser |
An API key belongs to a workspace, not to a person. Anyone holding it can act as that workspace within the key's scopes, so keep keys on your servers and never put one in a browser or a mobile app.
Create a key
Owners and admins create keys under Settings → API keys (also linked from Developers). Give the key a name you'll recognise later, such as "Production web" or "Billing worker", and choose its scopes.
- The key looks like
kx_followed by 48 hexadecimal characters. - It is shown exactly once. Copy it into your secret store straight away. Koltrix stores only a hash and cannot show it again.
- The list shows each key's first characters, its scopes and when it was last used, so you can tell keys apart and spot unused ones.
export KOLTRIX_KEY="kx_..."Scopes
A key may carry several scopes. Give each key the fewest it needs. New keys
start with read and send.
| Scope | What it allows |
|---|---|
send | Send email with POST /api/v2/emails and through the SMTP relay. Also reads back your messages. |
read | Read your message log and message events, and read lists, subscribers and sequences. |
newsletter | Create, change and delete lists, subscribers, broadcasts and sequences. |
contacts | Reserved. No /api/v2 endpoint uses it today. |
* | Full access: every scope, now and in future. Use it sparingly. |
Scopes are fixed when the key is created. To change them, create a new key and revoke the old one.
Which scope each endpoint needs
| Endpoint | Scope |
|---|---|
GET /api/v2/me | Any valid key |
POST /api/v2/emails | send |
GET /api/v2/messages, GET /api/v2/messages/:id, GET /api/v2/messages/:id/events | read or send |
GET on lists, subscribers, sequences and sequence steps | read or newsletter |
| Every other list, subscriber, broadcast and sequence endpoint | newsletter |
| SMTP relay | send |
Make an authenticated request
GET /api/v2/me tells you which workspace a key belongs to and what it may do.
It is a good first call and a good health check.
curl https://api.koltrix.com/api/v2/me \
-H "Authorization: Bearer $KOLTRIX_KEY"{
"tenant": "acme",
"permissions": ["read", "send"]
}tenant is your workspace's short name.
Errors
| Status | Body | What to do |
|---|---|---|
401 | {"error": "missing Bearer token"} | Send the header as Authorization: Bearer kx_…, with the word Bearer and a space. |
401 | {"error": "invalid api key format"} | The token doesn't start with kx_. Check you copied the whole key. |
401 | {"error": "invalid or revoked api key"} | The key doesn't exist or was revoked. Create a new one. |
403 | {"error": "missing permission: send"} | The key is valid but lacks the scope. The message names it (send, read or newsletter). |
Endpoints that accept read or newsletter name only newsletter in their
403 message, and endpoints that accept read or send name read.
Rotate a key
Keys don't expire. To rotate one:
- Create a new key with the same scopes.
- Deploy it everywhere the old key is used, including SMTP settings.
- Revoke the old key under Settings → API keys.
Revoking takes effect on the next request: the old key gets 401 on the API
and 535 on the SMTP relay. A request that was already accepted finishes
normally.
Rotate straight away if a key is ever committed to a repository, pasted in a chat or printed in a log, and otherwise on a schedule that suits you.
Rate limits
Each API key may make 60 requests per minute to /api/v2. Over that, the
API answers 429 with a Retry-After header. This limit is separate from
your plan's send quota; both are explained in
Limits and quotas.
Calling the API from a browser
The API sends CORS headers only for Koltrix's own sites, so a call from your web page's JavaScript is refused by the browser. That is deliberate: a key in a web page is a key anyone can copy. Call the API from your server.
The Try it panels in the API reference are the one
exception. They run in your browser on docs.koltrix.com and send the key you
paste straight to api.koltrix.com, nowhere else.