Authentication

All API requests to Krafter Mail require authentication via an API key passed in the Authorization header as a Bearer token.

API Key Format

All Krafter API keys share a single prefix:

Prefix	Example
kr_live_	kr_live_abc123def456ghi789

Sandbox keys are issued from the same namespace and are distinguished by an is_sandbox flag set when the key is created in the dashboard — not by a separate prefix. A sandbox key sends from the shared @test.krafter.dev sender, is locked to the mail:send scope, and has hourly and daily caps. The full list of sandbox constraints is shown in the dashboard when you create the key.

Making Authenticated Requests

Include your API key in the Authorization header with the Bearer scheme:

curl https://app.krafter.dev/api/v1/emails \
  -H "Authorization: Bearer kr_live_abc123def456ghi789"

DANGER

Never expose your API key in client-side code, public repositories, or browser requests. API keys should only be used in server-side code.

API Key Scopes

Each API key is assigned one or more scopes that control what operations it can perform. Follow the principle of least privilege — only grant the scopes your application actually needs.

Scope	Permissions
mail:send	Send single and batch emails, cancel queued emails, manage suppressions
mail:read	List/get/export emails, fetch events, list streams, read stats
mail:webhooks	Full CRUD plus test delivery and rotate-secret on mail webhooks
domains:manage	Add, verify, and remove sending domains
templates:manage	Create, list, get, update, and delete email templates
*	Wildcard — grants every scope above

INFO

The legacy scope name webhooks:manage is still accepted by the webhook endpoints for older keys, but the canonical name surfaced in the dashboard is mail:webhooks. Prefer the canonical name when creating new keys.

Scope Examples

Transactional email service that only sends emails:

• mail:send

Monitoring dashboard that reads delivery data:

• mail:read

Full-access backend that manages everything:

• mail:send, mail:read, mail:webhooks, domains:manage, templates:manage

Creating API Keys

1. Log in to the Krafter Mail dashboard.
2. Go to Settings > API Keys.
3. Click Create API Key.
4. Enter a descriptive name (e.g., "Production Backend", "Staging Server").
5. Select the scopes you need.
6. Click Generate.

The full API key is displayed only once after creation. Copy it immediately and store it in a secure location such as an environment variable or secrets manager.

Revoking API Keys

To revoke an API key:

1. Go to Settings > API Keys in the dashboard.
2. Find the key you want to revoke.
3. Click Revoke.

Revoked keys immediately stop working. Any requests made with a revoked key receive a 401 Unauthorized response.

Authentication Errors

If the API key is missing, malformed, or has been revoked, the API returns 401 Unauthorized with a flat error string:

{
  "error": "Invalid or missing API key"
}

If the API key is valid but lacks the scope required for the endpoint, the API returns 403 Forbidden:

{
  "error": "Insufficient scope"
}

Common causes:

• Missing Authorization header
• Incorrect Bearer prefix (e.g., using Token instead of Bearer)
• Revoked or expired API key
• Calling an endpoint that requires a scope your key does not hold

Best Practices

• Rotate keys regularly. Create a new key, update your application, then revoke the old one.
• Use separate keys for each environment (staging, production) and each service.
• Store keys in environment variables, not in code or configuration files.
• Monitor key usage in the dashboard to detect unauthorized access.
• Use the narrowest scopes possible for each key.