Guides

Authentication and API keys

Every request carries an API key. Each key belongs to one account, holds only the scopes you gave it, and is shown to you once.

Send the key as a bearer token

Put the key in the Authorization header of every request, over HTTPS. Keys start with rmk_live_. The key decides the account, so there is no account id to pass.

Any request

curl https://app.rykonmail.com/api/v1/domains \
  -H "Authorization: Bearer $RYKON_MAIL_KEY"

A request with no key, or with a key in the wrong shape, is answered 401 before anything else happens:

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Send your API key as Authorization: Bearer rmk_... Make one in the console under Developers."
}

Create a key

Sign in to the console and open Developers. Only an owner or an admin of the account can make or revoke keys.
Name the key after the system that will use it, so you know what breaks when you revoke it.
Choose its scopes: the least that integration needs.
Copy the key. It is shown once and cannot be shown again.

A key is a password for your account

Keep it in your server's environment or a secret manager. Never put it in a browser, a mobile app or a repository: the API sends no CORS headers, on purpose, because a key in a web page would be handed to every visitor. If a key is exposed or lost, revoke it in the console and make another.

Scopes

A key can do only what its scopes allow. A call outside them is answered 403 forbidden, and the message names the scope the key is missing. Each operation in the reference shows the scope it needs.

Scope	Allows	Endpoints
domains:read	Read your domains and the DNS records that set them up.	3
domains:write	Add domains and ask for their records to be checked.	3
mailboxes:read	Read mailboxes, aliases and AI agents, and the agent messages waiting for approval.	5
mailboxes:write	Create and delete mailboxes and aliases, reset passwords, set up agents, and approve or reject what they send.	11
audience:read	Read contacts, topics, forms, campaigns with their reports, and automations.	17
audience:write	Add, import and change contacts, and create, test and schedule campaigns, forms, topics and automations.	31
sending:read	Read the transactional email log.	1
mail:send	Send transactional email.	1

Good practice

One key per system. Your app's sign-up flow and your billing job each get their own, so either can be revoked without touching the other.
Scopes as narrow as the job. A key that only sends receipts holds mail:send and nothing else.
Call the API from your server. Your frontend asks your backend, and your backend holds the key.
Rotate by overlap: make the new key, deploy it, then revoke the old one. A request with a revoked key is answered 401.

Agent keys are different

An AI agent gets a key of its own from its page in the console. It holds agent:mail alone and is bound to that one agent, so it reaches that agent's mailbox and nothing else. See Agents and MCP.