# Authentication, scopes, and rate limits

## API keys

Every API request must send an `Authorization: Bearer <key>` header. Keys look like:

```
mc_live_YJs9gvYaRhL-6An-hdHlmQb0pTqfGC38hbAT3WwGrs4
mc_test_abcdefghijklmnopqrstuvwxyz0123456789ABCD
```

The prefix tells you (and any code reviewer) whether the key is live or test data.

### How keys are stored

- Mobieus stores only a **SHA-256 hash** of the key — the plaintext is shown **once** at creation and is unrecoverable.
- Lookup uses constant-time comparison so attackers can't grind hashes by timing.
- The first ~12 characters are stored separately so the admin UI can identify the key by prefix without ever seeing the secret.

### Managing keys

Tenant super-admins manage keys at **`/admin/api-keys`**:

| Action | What happens |
|---|---|
| **Create key** | Generates a fresh key. The plaintext is shown once on the next page — copy it now, you cannot recover it. |
| **Revoke** | Immediate. The next request with that key returns `401 invalid_api_key`. Not reversible. |
| **Expire** | Optional `expires_at`. Keys past their expiry start returning `401` automatically. |

Every create and revoke is audit-logged.

## Scopes

Every key has one or more scopes. Endpoints check the scope before processing — a key without `events:read` calling `GET /api/v1/events` gets `403 insufficient_scope`.

| Scope | Lets the key… |
|---|---|
| `events:read` | Read `/api/v1/events` |
| `users:read` | Read `/api/v1/users` and `/api/v1/users/{id}` |
| `posts:read` | Read `/api/v1/posts` and `/api/v1/posts/{id}` |
| `webhooks:read` | List webhook endpoints + delivery history *(Phase 2)* |
| `webhooks:manage` | Create / update / delete webhook endpoints *(Phase 2)* |

**Principle of least privilege**: only grant the scopes the integration actually needs.

## Tenant isolation

A key is bound to the tenant it was minted in. A `mc_live_…` key from `support.mobieus.io` will not authenticate against `fort-smith-live.mobieus.io`, and there is no API surface to query a different tenant's data with it. Every endpoint mounts under the tenant subdomain; tenant scoping happens at the database connection layer, so cross-tenant queries are structurally impossible.

## Rate limits

Default: **600 requests per minute per key**. Every response carries:

- `X-RateLimit-Limit` — the ceiling
- `X-RateLimit-Remaining` — what's left in the current window
- `X-RateLimit-Reset` — Unix timestamp when the window resets

On exceed you get `429 Too Many Requests` plus a `Retry-After: <seconds>` header. Back off, then retry.

If you need a higher limit, raise it for your tenant by adjusting `api.rate_limit_per_minute` in `config/app.ini` or contact ops.

## Request IDs

Every response carries `X-Request-Id: req_xxxxxxxxxxxxxxxx`. The same id appears in the JSON body as `request_id`. Include it whenever you contact support — it lets us correlate your call with the server log instantly.

## Error envelope

Every error response uses the same JSON shape:

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid, revoked, or expired.",
    "request_id": "req_3f2b8d9c10ab7c92"
  }
}
```

Common codes:

| HTTP | `error.code` | Meaning |
|---|---|---|
| 401 | `missing_authorization` | No `Authorization` header. |
| 401 | `invalid_authorization` | Header wasn't a Bearer token. |
| 401 | `invalid_api_key` | Bad key, revoked, or expired. |
| 403 | `insufficient_scope` | Key valid but missing the required scope. |
| 400 | `invalid_since` / `invalid_until` | Date filter wasn't ISO-8601. |
| 404 | `user_not_found` / `post_not_found` | Resource doesn't exist. |
| 429 | `rate_limited` | Slow down — see `Retry-After`. |
| 500 | `internal_error` | Server error. Include the `request_id` when reporting. |