Authentication

API keys

An API key belongs to exactly one project. Every resource read or written through the API (emails, contacts, audiences, broadcasts, domains) is implicitly filtered by that project id. There is no way to reach another project's data with a given key, even at the 404 level.

Create and revoke keys from the sevk dashboard under Settings → API Keys. Revocation takes effect on the next request.

Sending the key

Pass the key as a bearer token on every request:

Authorization: Bearer sevk_xxxxxxxxx

curl https://api.sevk.io/emails \
  -H "Authorization: Bearer sevk_xxxxxxxxx" \
  -H "Content-Type: application/json"

Through the SDK

The clients take the key in their constructor and attach the header themselves:

import { Sevk } from 'sevk'

const sevk = new Sevk(process.env.SEVK_API_KEY!)

import os

from sevk import Sevk

sevk = Sevk(os.environ['SEVK_API_KEY'])

Domain-pinned keys

An API key can optionally be bound to a single verified domain. When a key has a domainId, every POST /emails, POST /emails/bulk, and POST /broadcasts/:id/send request is inspected: if the from address (or the broadcast's domainId) is not on that domain, the request is rejected with 403 before any queue work happens. Pinning is the right choice for per-tenant sending where one key must never send as another tenant.

Sending from multiple regions

When the same hostname is registered in several regions, bind each sending key to the domain record for the region you want to use. A key bound to example.com in eu-central-1 sends from that region; a key bound to its eu-west-1 record sends from Ireland. Both can use [email protected] as the sender. This applies to single sends, bulk sends, and SMTP authentication. Broadcasts use the region of their selected domain record.

Keys scoped to all domains do not select a specific region when several verified records match the sender. Use a domain-pinned key when region selection matters. sevk does not automatically switch regions when a send fails.

Capability scopes

Every endpoint checks one or more capabilities on the presenting key. A key can be issued with full access, or with an arbitrary subset of scopes. Revoking a scope takes effect on the next request. No token re-issue required.

Emails

Contacts

Audiences

Templates

Broadcasts

Domains

Topics

Segments

Subscriptions

Webhooks

Activity

Usage

Outbound

Inbound

AI

Key hygiene

• Server-side only. Keys carry full send authority for the project. Never embed one in a mobile app, desktop app, or browser bundle.
• One key per integration. If a key leaks, you want to revoke it without taking down the rest of your stack.
• Scope minimally. A webhook worker that only looks up emails should have email:read, not email:send.
• Pin to a domain when you can. A pinned key can only send as that domain even if it is exfiltrated.
• Rotate on suspicion. Keys are cheap to issue. Rotate before you investigate, not after.

Loading from env

SEVK_API_KEY=sevk_xxxxxxxxx

import { Sevk } from 'sevk'

if (!process.env.SEVK_API_KEY) {
  throw new Error('SEVK_API_KEY is not set')
}

const sevk = new Sevk(process.env.SEVK_API_KEY)