Tokens and security
Which credential to use for what, who may do what, and what ATLAS never lets through.
2 min read
Token kinds
A token belongs to one brand. The plain value is shown once, when the token is created, and ATLAS keeps only a hash. Only an admin can create or revoke tokens, apart from short preview tokens.
| Kind | Reads | Who creates it | Expiry |
|---|---|---|---|
read | Published content through /v1/public | Admin | Optional, 1 to 43200 minutes. Without one it never expires. |
preview | Drafts too, never cached | Admin, or any member for the editor's own preview | Required. Up to 7 days for an admin, up to 2 hours for a member. |
agent | A scoped door for an outside agent (read, and draft-only writes) | Admin, when the brand allows agents | 15 minutes to 90 days, 30 days by default. |
developer | Pushes a theme from the atlas command line | Admin | 15 minutes to 90 days, 30 days by default. |
- Keep read tokens in server-side environment variables. Never ship one in browser code or commit it.
- Rotate by creating a new token, deploying it and then revoking the old one.
- A preview token must expire. Give it the shortest life that fits the review.
- An agent token never publishes: its writes are drafts that a person approves.
How to send a token
# Either header works
curl -s "https://api.atlascms.id/v1/public/page?path=/" -H "Authorization: Bearer $ATLAS_TOKEN"
curl -s "https://api.atlascms.id/v1/public/page?path=/" -H "X-Atlas-Token: $ATLAS_TOKEN"A token in the query string is never accepted. A site that calls from its server may add X-Atlas-Client-Ip and X-Atlas-Client-User-Agent so rate limits judge the visitor, not the server.
Roles
Every member of a brand has one role. The API checks it before it looks at the request body.
| Role | Can |
|---|---|
| Editor | Write drafts, request a review, upload media, create terms, and move pages that are not live. |
| Publisher | Everything an editor can, plus publish, schedule, roll back and delete, change live pages, redirects, menus, fragments and strings, and read and manage leads. |
| Admin | Everything a publisher can, plus settings, theme, members, tokens, integrations, secrets, imports and the audit log. |
A custom content type can set a minimum role. A caller below it gets 403 on that type's entries. A brand always keeps at least one admin.
What ATLAS enforces
- Brand isolation. Every brand-owned row is scoped to its brand and the scope fails closed. A record id from another brand is a 404.
- Encrypted secrets. Integration keys and webhook secrets are write-only: they are stored encrypted and are never returned, logged or put in a URL.
- Audit trail. Every change to live output writes an audit row with ids, never content bodies or secrets.
- Safe links and markup. Every stored link is checked on save and again on output, and rich text is cleaned on save.
- Safe outbound calls. Webhooks, CRM forwards and CDN purges go over HTTPS to public addresses only, never to private networks.
- Signed webhooks. Every delivery is signed with HMAC-SHA256. See webhooks.
- AI is a draft. AI output lands as a draft revision. The one exception is an autopost setting an admin switches on, which is off by default and audited.
The plain-language summary lives on the Security page. To report a vulnerability, write to [email protected].
Was this page helpful?
Suggest a change
Public API reference