Authentication

All Zyphr API requests require authentication using an API key. You can create and manage API keys through the Dashboard or the API. This guide covers how to create and use API keys securely.

API Key Types

Zyphr supports two types of API keys:

Key Type	Prefix	Purpose
Live	zy_live_*	Production use - messages are delivered
Test	zy_test_*	Development/testing - messages are stored but not delivered

Creating API Keys

Via Dashboard

1. Navigate to API Keys in the sidebar
2. Click Create API Key
3. Enter a descriptive name (e.g., "Backend Server", "Development")
4. Choose the mode (Live or Test)
5. Select permission scopes (e.g., email:send, push:send, subscribers:read)
6. Optionally set an expiration date
7. Click Create
8. Copy your API key — you won't be able to see it again

Via API

Create new API keys programmatically using an existing key or JWT session:

curl -X POST https://api.zyphr.dev/v1/api-keys \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "mode": "live",
    "scopes": ["email:send", "push:send"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

warning

Copy your API key immediately — the full key is only returned once at creation. If you lose it, you'll need to create a new one.

Using API Keys

Include your API key in the X-API-Key header with every request:

curl -X POST https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "html": "<p>Hi!</p>"}'

With SDKs

Node.js

import { Zyphr } from '@zyphr-dev/node-sdk';

const zyphr = new Zyphr({
  apiKey: process.env.ZYPHR_API_KEY,
});

Python

from zyphr import Zyphr

zyphr = Zyphr(api_key=os.environ["ZYPHR_API_KEY"])

Managing API Keys

Via Dashboard

1. Navigate to API Keys in the sidebar
2. View all keys with their mode (Live/Test), status, scopes, and last used timestamp
3. Revoke a key by clicking the Revoke button

Via API

# List all API keys
curl https://api.zyphr.dev/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a specific API key
curl https://api.zyphr.dev/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Revoke an API key
curl -X DELETE https://api.zyphr.dev/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Scopes

API keys can be scoped to limit their permissions:

Scope	Description
email:send	Send emails
email:read	Read email messages and events
push:send	Send push notifications
push:read	Read push messages
push:write	Manage push configuration
sms:send	Send SMS messages
sms:read	Read SMS messages
inbox:send	Send in-app notifications
inbox:read	Read inbox data
domains:read	Read domain configuration
domains:write	Manage domains
api_keys:read	List API keys
api_keys:write	Create/revoke API keys
*	Wildcard — all permissions

IP Whitelisting

Restrict API key usage to specific IP addresses or CIDR ranges:

Via Dashboard

On the API Keys page, click on a key to view its details and configure IP restrictions.

Via API

curl -X PUT https://api.zyphr.dev/v1/api-keys/KEY_ID/ip-whitelist \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_addresses": ["203.0.113.0/24", "198.51.100.42"]
  }'

Security Best Practices

Store Keys Securely

Never commit API keys to version control. Use environment variables:

# .env (never commit this file!)
ZYPHR_API_KEY=zy_live_xxxxxxxxxxxx

// Access via environment variable
const apiKey = process.env.ZYPHR_API_KEY;

Use Test Keys in Development

Always use zy_test_* keys during development to avoid accidentally sending real notifications:

# Development
ZYPHR_API_KEY=zy_test_dev_key_here

# Production
ZYPHR_API_KEY=zy_live_prod_key_here

Rotate Keys Regularly

Rotate your API keys periodically:

1. Create a new API key (Dashboard or API)
2. Update your application to use the new key
3. Verify everything works
4. Revoke the old key (Dashboard or API)

Use Scoped Keys

Create keys with only the permissions they need. A backend service that only sends emails should use a key scoped to email:send, not *.

Rate Limiting

API keys are subject to rate limits based on your plan:

Plan	Requests/second
Free	10
Pro	100
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Revoking Keys

Via Dashboard

1. Go to API Keys in the sidebar
2. Find the key you want to revoke
3. Click the Revoke button
4. Confirm the action

Via API

curl -X DELETE https://api.zyphr.dev/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

caution

Revoking a key is immediate and permanent. Any applications using the key will stop working.

Troubleshooting

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Common causes:

• Missing X-API-Key header
• Typo in the API key
• Key has been revoked
• Key has expired

403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have permission"
  }
}

Common causes:

• Using a test key for a production-only endpoint
• Key doesn't have the required scope
• IP address not in the key's whitelist