---
title: Authentication
slug: authentication
docTags: 
createdAt: 2026-06-02T09:00:53.233Z
---

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

## Bearer token (recommended)

Send your key in the `Authorization` header:

```bash
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)

:::hint{type="warning"}
**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:

```bash
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:

```bash
# 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](build-an-app) and [MCP](mcp). |

## Authentication errors

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

```json
{
  "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.