# Authentication

> Authenticate every API request with a Bearer API key.

The MailBlastr API authenticates with an API key sent as a Bearer token. Keys are created in the dashboard under **API Keys** (or via the [API](https://www.mailblastr.com/docs/api/api-keys-create)); the full key is shown **once** at creation and stored only as a hash afterward.

## Base URL

The API is built on **REST** principles and is served over **HTTPS only** — plain HTTP is not supported. Every request goes to the same base URL:

```text
https://api.mailblastr.com
```

## Authorization header

Add an `Authorization` header whose value is `Bearer ` followed by your API key:

```bash
Authorization: Bearer mb_xxxxxxxxx
```

> **Warning:** Treat API keys like passwords. Never commit them or expose them in client-side code — call the API from your server.

## User-Agent header

Every API request must also include a `User-Agent` header. Requests without one are rejected with a `403`, even when the API key is valid. Most HTTP clients set this automatically, but if you build requests by hand, set it explicitly:

```text
User-Agent: my-app/1.0
```

> **Warning:** If you get a `403` despite a valid API key, a missing `User-Agent` header is the most likely cause.

## Permissions

Each key has a permission level:

| Permission | Can do |
| --- | --- |
| **full_access** | Send email **and** manage resources (domains, audiences, contacts, campaigns, API keys). |
| **sending_access** | Send email only. Cannot create or delete domains, audiences, or other keys. |

A `sending_access` key is the safest choice for a server that only needs to send transactional email. See [Create API key](https://www.mailblastr.com/docs/api/api-keys-create).

## Rate limit

The default rate limit is **5 requests per second per team**, applied across all API keys on the team. Exceeding it returns a `429`. Trusted senders can request an increase.

## Errors

A missing key returns `401 missing_api_key`; an invalid or revoked key returns `403 invalid_api_key`; a key without the required permission returns `422 invalid_access`; a missing `User-Agent` returns `403`. See [Errors](https://www.mailblastr.com/docs/api/errors).