# Authentication

> Authenticate every API request with a Bearer API key.

The SendPing API authenticates with an API key sent as a Bearer token. Keys are created **in the dashboard** under **API Keys** — see [Create an API key](https://www.sendping.co/docs/create-an-api-key). 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://www.sendping.co/api
```

## 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). |
| **sending_access** | Send email only. Cannot create, update, or delete domains, audiences, contacts, or campaigns. |

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

> **Warning:** Neither permission covers API keys themselves. Creating a key, changing its permission or domain restriction, and revoking it are **dashboard-only** actions: `POST /api-keys`, `PATCH /api-keys/:id`, and `DELETE /api-keys/:id` refuse every API-key caller with `403 dashboard_only`, whatever its permission. Sign in to the dashboard to manage keys. This is a breaking change — if you previously automated those three calls with a full-access key, that automation now fails and the steps must be done in the dashboard.

## Rate limit

Rate limits are enforced over **60-second windows, per client IP** — not per key or per team: roughly **30 requests per minute** on the send endpoints, **20 per minute** on expensive endpoints (such as AI and support), and **120 per minute** on general public endpoints. There is no separate burst allowance, and requests from multiple services behind the same address count together. Exceeding a limit returns a `429`. See [Account quotas and limits](https://www.sendping.co/docs/kb/quotas).

## 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 `401 restricted_api_key`; an API key calling a dashboard-only endpoint returns `403 dashboard_only`; a missing `User-Agent` returns `403`. See [Errors](https://www.sendping.co/docs/api/errors).