API keys

API keys let apps, CI pipelines and AI agents use the API and MCP. A key starts with smk_.

Each key works in one universe, with one role: viewer, member or admin. A key can never be owner.

Creating a key

You need the admin role in the organization.

1. On your account page, go to API keys and choose New key.
2. Say what it is for, such as “CI pipeline” or “AI agent”.
3. Pick the universe.
4. Pick the role:
   • Member: send mail and manage people. Right for most apps and agents.
   • Admin: also logins, rules and webhooks.
   • Viewer: read only.
5. Copy the key. It is shown only once.

The list of keys shows each key’s name, its first characters (the prefix), its universe, role and when it was made.

Using a key

curl -s https://c1.simmail.dev/api/me -H "Authorization: Bearer smk_your_key"

Send it to your universe’s server, the API address on your account page. The key already says which universe it is for, so you do not need X-Simmail-Universe. If you send that header with a different universe, the request fails with 403.

Revoking a key

Choose Revoke next to it. Anything using it stops working at once.

Good habits

• One key per system: CI, the staging app, each AI agent. Then you can revoke one without breaking the rest.
• The lowest role that works. Most tests need member; only set-up scripts that create logins or change rules need admin.
• Keep keys in your CI’s secret store, not in code.
• A viewer key can still read everything in its universe, including the passwords of its SMTP logins.