Authentication

Every request except /health and the public tracking and unsubscribe links needs a key in the Authorization header:

Authorization: Bearer fs_live_4f8KqZ0xY2mB7nR1tV9cL3pW6sD5hJ0a

There are two kinds of key.

Project API keysCopy Anchor Link

A project key is fs_live_ or fs_test_ followed by 32 letters and digits. You create keys in the dashboard, with the CLI or with the admin API.

• The full key is shown once, in the response that creates it. Flaresend stores only the first 12 characters (the prefix, for example fs_live_4f8K) and a SHA-256 hash of the key. A lost key can't be recovered; create a new one and revoke the old one.
• The key picks the project. There is no project parameter on /v1 routes.
• Keys can expire. A key created with expiresAt stops working at that time.
• Keys can be revoked at any time from the dashboard, the CLI or the admin API. Revoking is immediate and can't be undone.
• Last use is recorded. Each key has a lastUsedAt time, updated at most once a minute.

Keep keys on the server. Anyone with a live key can send email from your project's domains.

Test keysCopy Anchor Link

A fs_test_ key goes through the same validation as a live key, but nothing is ever sent:

• POST /v1/emails returns status 200 and status: "test", and the email is stored with status test.
• Test sends don't count against the rate limit or the daily limit.
• The suppression list isn't checked.
• Everything else (reading emails, webhooks, templates, contacts) works the same as with a live key.

Use test keys in development and CI. See Test mode.

The admin keyCopy Anchor Link

Routes under /v1/admin take the mailer's ADMIN_API_KEY secret instead of a project key. It can create projects and keys, read every project's emails and manage the suppression list, so treat it like a root password. The dashboard doesn't use it: it talks to the mailer over a service binding. See the Admin API.

A project key sent to /v1/admin is rejected, and so is the admin key sent to other /v1 routes.

Workers don't need a keyCopy Anchor Link

Workers in the same Cloudflare account can call the mailer over a service binding with the RPC client. Only Workers in your account can bind to it, so the project slug is trusted and no key is used. The project must have RPC enabled (rpcEnabled, on by default).

ErrorsCopy Anchor Link

{
  "error": {
    "type": "authentication_error",
    "code": "revoked_api_key",
    "message": "this API key has been revoked"
  }
}