Authentication
Bearer API keys, key types, scopes, and the multi-tenant profile header.
Preview
Preview: the API and MCP server are in private beta; details may change.
Every request to https://api.getimma.com/v1 authenticates with a Bearer API key in the Authorization header. There is no separate OAuth flow for the REST API: IMMA AI holds each connected account's TikTok/Meta tokens, and your API key never touches them directly. (The MCP server is different: it also supports an OAuth 2.1 login for clients like ChatGPT and Claude.ai/Claude Desktop custom connectors that cannot accept a static key, alongside the same Bearer API key used here. See MCP: which client uses which auth.)
Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxxKey types
| Prefix | Use | Behavior |
|---|---|---|
imma_live_ | Production | Posts to real connected accounts and counts against plan quota |
imma_test_ | Development | Only works against sandbox accounts marked test in the workspace, never publishes publicly, does not count against plan quota |
Generate and revoke keys from the dashboard (/developers/api-keys). A key is shown once at creation; after that only its 8 character prefix is visible. Revoking a key takes effect immediately.
Scopes
A key can be limited to one or more scopes:
| Scope | Grants |
|---|---|
posts:write | Create, update, cancel and retry posts |
posts:read | List and read posts |
accounts:read | List and read connected accounts and their capabilities |
accounts:write | Create connect links, refresh capabilities, disconnect accounts |
analytics:read | Read post and account metrics |
inbox:write | Read, reply to and hide comments |
webhooks:write | Manage outgoing webhook endpoints |
Request only the scopes your integration needs. A request that touches a resource outside the key's scopes returns 403 insufficient_scope.
Multi-tenant requests
If your workspace manages more than one end customer, each customer is a separate profile (prof_..., see Concepts). Send the optional header to scope a whole request to one profile:
IMMA-Profile: prof_01J...For example, GET /v1/accounts with this header only returns that profile's connected accounts, even if the key itself has access to many profiles.
Example: checking a key works
curl https://api.getimma.com/v1/accounts \
-H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"Errors
| Code | HTTP | When |
|---|---|---|
unauthorized | 401 | Missing or invalid API key |
insufficient_scope | 403 | Key does not have the scope this endpoint requires |
test_key_live_account | 403 | An imma_test_ key was used against a non sandbox account |
See Errors for the full list and the shared error shape.