The API supports two authentication models: API keys for service-to-service calls and user tokens for end-user actions. This article focuses on API keys.
Creating a Key
- Open Architect Panel → API → Keys and click New Key.
- Friendly name — descriptive (e.g. “Salesforce nightly sync”).
- Scopes — pick the least-privilege set this key needs (e.g. read+write on a specific datastore, no admin).
- Optional restrictions:
- Allowed source IPs — restrict to your integration server's CIDR.
- Allowed endpoints — whitelist paths the key can hit.
- Expiry date — force rotation after N days.
- Generate. The key is shown once. Copy it into your secrets manager immediately.
Using the Key
Include the key in the Authorization header:
Authorization: Bearer am_live_xxxxxxxxxxxxxxxxxxxx
Best Practices
- One key per integration. Easier to rotate, easier to revoke.
- Least privilege. Reads-only key for a reporting integration, not a write key.
- IP allowlist. If the integration server has a fixed IP, lock the key to it.
- Rotate annually. Set expiry to force a rotation reminder.
- Never embed in client-side code. Keys in browser JS or mobile binaries are extractable.
Worked Examples
- Salesforce sync: Read+write on Customers, Orders. IP-locked to Salesforce's static egress. Expires in 1 year.
- Internal reporting: Read-only across all datastores. No IP lock (runs from BI tools). Expires in 90 days.
- Slack notifier: No read scope; webhook-only. Restricted to
/api/notifications/slackendpoint. - Mobile backend: Backend proxies user actions; mobile app uses user tokens, backend uses an admin-scoped service key.