# API Authentication and API Keys

Every OmniSocials API request requires a Bearer token in the `Authorization` header. Tokens are long-lived API keys created from the dashboard.

```
Authorization: Bearer omsk_live_<YOUR_KEY>
```

## Create an API key

1. Sign in to [app.omnisocials.com](https://app.omnisocials.com)
2. Open **Settings → API**
3. Click **Create API Key**
4. Name the key (e.g. "Zapier", "Internal automation"), pick the scopes it needs, and save
5. Copy the key. It is shown exactly once and cannot be retrieved later

Keys starting with `omsk_live_` hit production. Keys starting with `omsk_test_` hit the test environment and never touch real social accounts. Test mode is useful for CI and local development.

## Scopes

Every key is scoped to a subset of the API. A key only has access to the scopes you selected when you created it.

| Scope | Grants access to |
|-------|------------------|
| `posts:read` | `GET /posts`, `GET /posts/:id` |
| `posts:write` | `POST /posts/create`, `PATCH /posts/:id`, `DELETE /posts/:id`, publish endpoints |
| `media:read` | `GET /media`, `GET /media/:id`, `GET /folders` |
| `media:write` | `POST /media/upload`, `POST /media/upload-from-url`, `PATCH /media/:id`, `DELETE /media/:id` |
| `accounts:read` | `GET /accounts`, `GET /accounts/:id` |
| `analytics:read` | `GET /analytics/*` endpoints, `GET /posts/recent-platform` |
| `webhooks:manage` | Full CRUD on webhooks, including secret rotation |

Requests made with a key missing the required scope return `403 Forbidden`. Add the missing scope by creating a new key, not by editing an existing one.

## Rotating and revoking keys

Revoke a key from **Settings → API** at any time. Revocation is immediate. In-flight requests using a revoked key fail with `401 Unauthorized` on the next call.

To rotate a key without downtime, create the new key first, update your integration, and only then revoke the old key.

## Security notes

- Never commit API keys to source control. Load them from environment variables or a secrets manager.
- Use test mode keys (`omsk_test_`) for local development and CI. They cost you nothing if leaked.
- A compromised key can do anything its scopes allow. Scope keys narrowly.
- Tokens do not expire automatically. Rotate them periodically as a hygiene practice.