Authentication
How to authenticate requests to the Emofy Platform API — bearer tokens, org context, scopes, and tiers.
Every partner API request must be authenticated. The Emofy Platform uses
bearer tokens in the standard Authorization header.
Bearer token
Authorization: Bearer <your-credential>Your API credential authenticates as your organization. It is issued from the Developer Portal and must be kept server-side — treat it like a password.
Organization context
A credential is bound to one organization, so the API already knows your tenant. For tooling that operates across orgs, two optional headers make the context explicit:
| Header | Purpose |
|---|---|
X-Org-Id | The organization the request targets. |
X-Org-Role | The role to act as within that organization. |
A cross-org credential or cursor returns 403 forbidden / 400 invalid_cursor
rather than silently leaking another tenant's data.
Scopes
Endpoints require scopes — granular permissions like tasks:read,
tasks:write, or feed:moderate. A request whose credential lacks the required
scope returns 403 forbidden.
For EMAs (Embedded Mini Apps), scopes are requested through the EMA manifest and granted by the user. The full catalog — with sensitivity tiers and the SDK methods each scope unlocks — is in EMA Scopes.
Rate-limit tiers
Each credential belongs to a rate-limit tier (free / standard / premium /
unlimited). Responses carry X-RateLimit-* headers, and a 429 rate_limit_exceeded includes a Retry-After. The SDK retries 429/5xx
automatically with Retry-After-aware backoff. See
Usage & Quota and
Tier Reference.
Errors
Auth failures use the V1 error envelope with a machine-readable code:
code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid credential. |
forbidden | 403 | Authenticated but lacking the scope/role/org. |
rate_limit_exceeded | 429 | Tier limit hit — back off per Retry-After. |
See the API Reference for the full error catalog and the response envelope.