Authentication

3AVA Mail uses bearer-token authentication. Every authenticated request carries an Authorization header:

Authorization: Bearer am_YOUR_KEY

That’s it.

Creating keys

Keys are created in the dashboard (API Keys → Create) or via the POST /api-keys endpoint. The full token is shown once at creation — store it immediately. After that, only the prefix (e.g. am_HSjf...) is retrievable.

Permission levels

Permission	Can do	Use case
full_access	Everything: send, list management, domains, IP pools, webhooks	Server-side admin tools
sending_access	Send emails, read campaigns + lists, manage webhooks. Cannot modify domains or IP pools.	Application servers, deployment pipelines

Pick sending_access for app-server keys. Pick full_access only for a small number of admin tools.

Scoping to a single domain

A key can be locked to one domain by passing domain_id at creation:

curl -X POST https://mail.3ava.com/api/api-keys \
  -H "Authorization: Bearer am_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-emails",
    "permission": "sending_access",
    "domain_id": "e04570c0-c0f7-4c75-8fd1-be90476b17a3"
  }'

Keys scoped this way reject any from address whose domain doesn’t match. This is the right pattern when you have one app per domain.

Key rotation

To rotate a key:

1. Create the new key.
2. Roll it out to your app.
3. Delete the old one with DELETE /api-keys/{id}.

There’s no native expiry — you rotate by creating-then-deleting.

What gets logged

Every authenticated request is recorded in the audit log with:

• The key prefix (not the full token)
• HTTP method + path
• Source IP
• Status code
• Timestamp

Audit logs are visible in the dashboard under Settings → Audit Log.

Key handling rules

• Never embed a key in browser-side JavaScript or a mobile app binary.
• Use environment variables, not source-tree config files.
• Use a separate key per environment (production, staging, local).
• If a key leaks, delete it immediately — there’s no “disable temporarily” state.