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.
Text
Create an API key
- Sign in to app.omnisocials.com
- Open Settings → API
- Click Create API Key
- Name the key (e.g. "Zapier", "Internal automation"), pick the scopes it needs, and save
- Copy the key and store it somewhere safe. Members who can manage the organisation's API can copy it again later from the key list under Settings → API
Every key starts with omsk_live_ and works on your real, connected social accounts. There is no separate test environment or test key, so point CI and local development at a workspace whose accounts you can post to safely, or create drafts (they never publish on their own).
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 |
inbox:read | Opt-in. GET /inbox/*: conversations, messages, and the next unanswered item |
inbox:write | Opt-in. Replies, marking read, hiding and deleting comments |
automations:read | Opt-in. GET /automations, GET /automations/:id, and the activity log |
automations:write | Opt-in. Create, update, and delete automations, and comment_dm_automation on posts |
The first seven scopes are the default set. The inbox and automation scopes are opt-in: turn on Social Inbox access or Automations when you create the key. Existing keys never get them automatically.
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.
- Give the keys you use in local development and CI only the scopes they need, and revoke them when a project ends.
- A compromised key can do anything its scopes allow. Scope keys narrowly.
- Tokens do not expire automatically. Rotate them periodically as a hygiene practice.