API Key Management

API keys authenticate applications that send emails or read data through the Relay API. Each key has specific scopes that control what it can access.

Creating an API Key

1. Go to API Keys in the left sidebar
2. Click Create Key
3. Enter a descriptive name (e.g., PSA Ticket Notifications - Production)
4. Select one or more scopes (see below)
5. Optionally set an expiration date
6. Click Create
7. Copy the full key from the modal — it's shown only once

The key format is relay_key_ followed by a random string. After creation, only the last 4 characters are visible in the dashboard.

⚠️The full API key is displayed exactly once at creation time. Store it in a secure location such as a Key Vault or environment variable. If you lose the key, revoke it and create a new one.

Scopes

Each API key can have one or more scopes that control its permissions:

Scope	Allows
send	Send single emails (POST /api/send, POST /api/send-template)
send-batch	Send batch emails (POST /api/send-batch) — also requires send
read-logs	Read email logs, stats, and analytics (GET /api/logs, /api/stats, /api/analytics)
manage-domains	Add, verify, and remove sending domains
manage-templates	Create, update, delete, and test email templates
manage-suppressions	View, add, remove, import, and export suppression list entries
admin	Full access — includes all scopes plus settings and key management

Recommended Key Configurations

Use Case	Scopes
Application sending emails	send
Application sending batches	send, send-batch
Monitoring/reporting tool	read-logs
DevOps automation	manage-domains, manage-templates
Full management	admin

💡Follow the principle of least privilege. A key that only sends emails should only have the send scope. Don't grant admin to application keys.

Using API Keys

Include the key in the X-Relay-Key header on every API request:

curl -X POST https://api.theonerelay.app/api/send \
  -H "Content-Type: application/json" \
  -H "X-Relay-Key: relay_key_abc123..." \
  -d '{ "from": "[email protected]", "to": ["[email protected]"], "subject": "Hello", "html": "<p>Hi</p>" }'

Requests without a valid key return 401 Unauthorized. Requests with a key that lacks the required scope return 403 Forbidden.

Key Expiration

Keys can have an optional expiration date. After expiration, any request using the key returns 401 Unauthorized. Use expiration for:

• Temporary integrations or testing
• Compliance requirements that mandate key rotation
• Contractor or third-party access

Keys without an expiration never expire unless manually revoked.

Viewing Keys

The API Keys page shows all keys for your tenant:

• Name — Descriptive label
• Key preview — Masked format showing only the last 4 characters
• Scopes — Badges showing granted permissions
• Last used — Timestamp of the most recent API call with this key
• Expires — Expiration date or "Never"
• Created — Creation timestamp

Updating a Key

Click a key to edit its name, scopes, or expiration. Changes take effect immediately. You cannot change the key value itself — to rotate, create a new key and revoke the old one.

Revoking a Key

1. Click the delete icon next to the key
2. Confirm revocation

Revocation is immediate and permanent. Any application using the revoked key will start receiving 401 Unauthorized responses.

Key Rotation Best Practices

1. Create the new key with the same scopes
2. Update your application's environment variable or secret store with the new key
3. Deploy the application
4. Verify sends are working with the new key (check Email Logs)
5. Revoke the old key

ℹ️Always create the new key before revoking the old one to avoid downtime. Run both keys in parallel until you've confirmed the new key works.

Environment Variable Convention

Store API keys in environment variables, not in code:

# .env (never commit this file)
RELAY_API_KEY=relay_key_abc123...

const relay = new RelayClient({
  apiKey: process.env.RELAY_API_KEY,
});