Authentication

This page covers the REST API. The MCP server also supports an OAuth 2.1 login for clients that need it, such as ChatGPT and Claude.ai/Claude Desktop custom connectors; see Which client uses which auth. REST API keys stay the only method for the API itself.

API keys

Every request authenticates with a Bearer token in the Authorization header:

Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx

There are two key types:

Prefix	Use	Behavior
imma_live_	Production	Posts to real connected accounts
imma_test_	Development	Only posts to sandbox accounts; never publishes publicly

Generate and revoke keys from the dashboard. A revoked key stops working immediately; there is no grace period.

Scopes

Keys can be limited to specific scopes: posts:write, posts:read, accounts:read, accounts:write, analytics:read, inbox:write, webhooks:write. Request only what your integration needs; a request that touches a resource outside the key's scopes returns 403.

Multi-tenant requests

If your workspace manages more than one end customer (a profile per customer, see Concepts), you can send the optional header:

IMMA-Profile: prof_01J...

This scopes the request to a single profile so, for example, GET /accounts only returns that customer's connected accounts even if your key has access to many.

What IMMA AI never asks you to hold

IMMA AI never asks your integration to store a TikTok or Meta access token. Connecting an account always goes through a hosted link (POST /connect/links) that the account owner opens directly; your API key only ever talks to IMMA AI, never to TikTok's or Meta's APIs on the owner's behalf. Platform tokens IMMA AI does hold are encrypted at rest and are never sold or exposed; see Platform rules for what each platform's access is used for.

Errors

An invalid or missing key returns 401. A valid key without the right scope, or an attempt to touch another workspace's data, returns 403. See Errors for the full list of error codes.