# Authentication and API keys

> How to create, use and protect the keys that authenticate the /v1 API.

## Create the key in the panel

In **API keys → Create key**, fill in:

| Field | What it is |
|---|---|
| **Name** | Up to 32 characters, to recognize the key later (`production`, `crm`) |
| **Permissions** | `send` (send messages), `read` (read connections, conversations and logs), `templates` (create and edit templates) and `admin` (everything). Tick only what the integration uses |
| **Connections** | **All connections** or only the selected ones. A key bound to connections cannot see the others |
| **Expiration** | 30, 90, 180 or 365 days, or **Never expires** |
| **Limit per minute** | From 1 to 6,000 requests per minute (default: 600). See [Limits](/en/api/limits/) |

Owners, admins and devs create keys. Only owners and admins can grant the `admin` permission. Once created, a key can be edited (name, permissions, connections, limit), disabled, re-enabled or revoked.

## Key types

|  | Organization key (`mj_`) | Connection key (`mjc_`) |
|---|---|---|
| Where to create | **API keys**, at the organization level | The connection's **API keys** tab |
| Reach | Any connection in the org; `connection_id` required on message routes | Only its own connection; `connection_id` is optional (if sent and different, 403 [`connection_not_allowed`](/en/errors#connection_not_allowed)) |
| Destinations | Global and any connection's | Only its own connection's, never global |
| Connections | List, update and disconnect | Read and update its own; cannot disconnect |
| Connection links | Yes | 403 [`organization_key_required`](/en/errors#organization_key_required) |
| Manage connection keys via `/v1` | Yes, with the `admin` permission | No |
| Events, deliveries, logs and costs | The whole org | Only the connection's (plus WABA events) |
| `GET /v1/me` | `api_key.kind = "org"`, null `connection_id` and `connection` | `api_key.kind = "connection"`, with `connection_id` and `connection { id, channel, label }` |

Permissions (`send`, `read`, `templates`, `commerce`, `admin`) apply to both types. Use one connection key per integration: it only sees its own number and does not need `connection_id`. Older organization keys bound to several connections keep working, but the panel no longer offers that option.

Templates, flows and catalogs belong to the WABA: a connection key that changes them also affects the sibling connections on the same WABA.

## The key is shown once

The full value, starting with `mj_` (organization) or `mjc_` (connection), only appears in the creation dialog. Messajo stores only a hash: neither the panel nor support can show it again. Lost it? Create another one and revoke the old one.

To recognize the key later, the panel shows the **visible prefix**, its first 10 characters (for example, `mj_A1b2c3d`). The same prefix comes back in the `api_key.start` field of `GET /v1/me`.

## Authorization: Bearer

Send the key in the `Authorization` header with the `Bearer` scheme, on every request:

```bash
curl https://api.messajo.com/v1/me \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

A panel session cookie **never** authenticates the `/v1` API: a request with only a cookie gets [`missing_api_key`](/en/errors#missing_api_key). Keys in the query string are not accepted either.

## Authentication errors

Every error uses the API's single error body, with a stable `code`:

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key: send Authorization: Bearer <key>",
    "meta_code": null,
    "retryable": false,
    "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b",
    "docs_url": "https://docs.messajo.com/errors#missing_api_key"
  }
}
```

| Status | `code` | When |
|---|---|---|
| 401 | [`missing_api_key`](/en/errors#missing_api_key) | The `Authorization: Bearer` header is missing |
| 401 | [`invalid_api_key`](/en/errors#invalid_api_key) | The key does not exist or was revoked |
| 401 | [`api_key_expired`](/en/errors#api_key_expired) | The key has expired |
| 401 | [`api_key_disabled`](/en/errors#api_key_disabled) | The key was disabled in the panel |
| 403 | [`insufficient_permissions`](/en/errors#insufficient_permissions) | The key lacks the permission the route requires |
| 403 | [`connection_not_allowed`](/en/errors#connection_not_allowed) | The key is bound to other connections |
| 403 | [`organization_key_required`](/en/errors#organization_key_required) | The route is organization-key only and the key is a connection key |

None of these errors goes away by retrying (`retryable: false`): fix the key or its permissions.

## Test in /reference

The interactive reference lives at `https://api.messajo.com/reference`.Paste the key under **Authentication** and use **Test request** to call the real routes, such as `GET /v1/me`.

The call goes from your browser to the server itself, on the same origin, without any third-party proxy. The [reference in these docs](/en/reference) is read-only and sends no requests.

## Rotate a key

In the panel, **Rotate** creates a new key with the same name, type, permissions, connection and limit, and shows the new value once. The old key keeps working for a **grace period**: **24 hours** (default) or **now**, which ends it immediately. The grace period never exceeds the original expiration. A disabled or expired key cannot be rotated.

Through `/v1`, an organization key with `admin` creates, rotates and revokes **connection keys** only (`grace`: `24h` or `now`). Organization keys are rotated in the panel; `/v1` returns 404 `not_found` for them:

```bash
# create a connection key
curl -X POST https://api.messajo.com/v1/connections/$CONNECTION_ID/api-keys \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "crm", "permissions": ["send", "read"]}'

# rotate
curl -X POST https://api.messajo.com/v1/api-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grace": "24h"}'

# revoke
curl -X DELETE https://api.messajo.com/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

The rotation response carries the new secret and `previous_key_expires_at`, when the old key's grace period ends. Full fields are in the [reference](/en/reference).

## Good practices

- **Environment variable or secrets manager**, never in code or in the repository.
- **Never in the browser or a mobile app.** Anyone can extract a key from a front end. Call Messajo from your back end.
- **One key per integration**, with the fewest permissions and, when possible, bound to the connections it uses. If one leaks, you revoke only that one.
- **Set an expiration** for test and third-party keys.
- **Rotate without downtime:** create the new key, swap it in the integration, check the old key's **last used** in the panel and only then revoke it. The **last used** time updates at most every ~5 s per replica and the request counter is not exact per call (key verification is cached for 5 s).
- **Leaked?** Revoke it right away. The next call with it already gets [`invalid_api_key`](/en/errors#invalid_api_key).

## X-Request-Id for support

Every response, success or error, carries the `X-Request-Id` header (`req_…`). The same value appears in `request_id` in error bodies and in `GET /v1/me`.

Log this value in your integration. When asking for help, send the `X-Request-Id`: with it, support finds the exact call without you sending the key.
