Authentication

6 min

Every v1 endpoint requires an API key. There are two ways to send it.

Bearer token (recommended)

Send your key in the Authorization header:

curl https://api.mailfloss.com/v1/organization \
  -H "Authorization: Bearer YOUR_API_KEY"

This is the preferred scheme for all new integrations. It keeps your key out of URLs, request logs, and browser history.

Legacy api_key query parameter (deprecated)

Prefer the Bearer header for every integration. The api_key query parameter is deprecated, and the original legacy API that relied on it sunsets June 1, 2027. Switching to Bearer is a one-line change (below).

Older integrations pass the key as a query parameter:

curl "https://api.mailfloss.com/v1/organization?api_key=YOUR_API_KEY"

This still works on v1, but it's soft-deprecated. Requests authenticated this way receive a Deprecation: true response header. Query parameters are easy to leak through server logs, proxies, and referrer headers.

Migrating to Bearer — move the key out of the query string and into the Authorization header:

# Before — legacy api_key query parameter
curl "https://api.mailfloss.com/v1/organization?api_key=YOUR_API_KEY"

# After — Bearer token (recommended)
curl https://api.mailfloss.com/v1/organization \
  -H "Authorization: Bearer YOUR_API_KEY"

If you supply both a Bearer token and an api_key parameter on the same request, the Bearer token wins.

Getting and managing your key

Create an API key in the mailfloss dashboard under Developers → API keys. Choose Full access, or Restricted to pick what the key can do. Keys are scoped to your organization.

Treat the key as a secret:

Keep it server-side. Never ship it in client-side JavaScript, mobile apps, or anything a user can inspect.

Don't commit it to source control. Load it from an environment variable or a secrets manager.

Rotate it if you suspect exposure.

Key formats

The prefix tells you what kind of credential it is:

Prefix	Meaning
mf_live_*	Full-access API key
mf_rk_*	Restricted API key. It can call only what you granted when you created it; anything else returns 403.
mf_oauth_*	OAuth access token for an app or MCP client a user connected. See Build an app on mailfloss and MCP.

Authentication errors

A missing or rejected key returns a 401 with an authentication_error:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "type": "authentication_error",
    "request_id": "req_a1b2c3"
  }
}

Common codes: missing_api_key (no key supplied) and invalid_api_key (key rejected). See the Errors guide for the full model.