Authentication
Organization API keys, scopes, rotation, and error shapes for the public API and MCP.
Authentication
Public REST and hosted MCP use organization API keys (not a user session cookie).
Create a key in the dashboard
- Open app.amplixa.io → Settings → API keys.
- Create a key: name, environment (
live/test), and scopes. - Copy the plaintext secret once — Amplixa does not show it again.
- Use it as
Authorization: Bearer amp_live_…(oramp_test_…).
You need the api_key.manage permission. API keys cannot mint other keys.
API keys
| Item | Detail |
|---|---|
| Header | Authorization: Bearer amp_live_… or X-Api-Key: amp_live_… |
| Ownership | Organization (not a user session) |
| Storage | Amplixa stores a peppered HMAC hash only |
| Manage | Dashboard Settings → API keys, or authenticated JWT + api_key.manage |
Environments
amp_live_— production dataamp_test_— sandbox-shaped keys (same org)
Scopes (allowlist)
Public keys may only use:
widget.create/read/update/delete/publishdomain.create/read/update/deleteorganization.read/update(webhooks use these)
Never grantable on a key: api_key.manage, billing, members, admin, analytics.
Defaults on create are typically read-only (domain.read, widget.read, organization.read) unless you request write scopes.
Rotation
- Create a new key
- Update clients / MCP config
- Revoke the old key in Settings → API keys
Errors
| Status | Meaning |
|---|---|
401 | Missing/invalid/revoked/expired key (generic message) |
403 | Missing scope, org header mismatch, or key used on a dashboard-only route (api_key_not_allowed) |
429 | Rate limited — honor Retry-After / retryAfterSec |
Dashboard JWT routes reject Amplixa API keys with 403 and code: api_key_not_allowed.
Org context is implicit from the key. If you send X-Org-Id, it must match the key’s organization.