Automation with machine tokens

Atlas is built to be driven by automation — your own scripts, CI jobs, or AI agents — without an interactive login. That access runs on scoped machine tokens: least-privilege bearer credentials you mint, scope, and revoke.

The design goal is simple: a token should be able to do exactly the job you gave it and nothing more, and a leaked token should be strictly bounded and instantly killable.

What a token is

A token is a 256-bit secret presented as a bearer credential:

Authorization: Bearer atlas_sk_<secret>

Atlas stores only a hash of the token plus a short display prefix — never the secret itself. The full secret is shown exactly once, at creation. Copy it straight into your secret manager; if you lose it, revoke it and mint a new one.

Creating a token

Token administration is interactive-admin-only. An admin (a human logged in through your identity provider) mints tokens; no machine token can create or revoke another token. This is a deliberate boundary — it means a leaked token can never escalate itself.

An admin creates a token with a name, the scopes it should carry, and an optional expiry:

curl -X POST $ATLAS/api/v1/admin/tokens \
  -H "Authorization: Bearer $ADMIN_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy-reporter",
    "scopes": ["deployments:read", "deployments:write"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

The response includes the full secret once:

{
  "id": "…",
  "name": "ci-deploy-reporter",
  "token_prefix": "atlas_sk_AbC12",
  "scopes": ["deployments:read", "deployments:write"],
  "token": "atlas_sk_<the full secret — store this now, it is not shown again>"
}

• name must match ^[a-z0-9][a-z0-9_-]*$.
• expires_at is optional; omit it for a non-expiring token (still revocable).

Scopes

Scopes are a least-privilege allowlist. Grant only what the job needs:

Scope	Grants
customers:read	Read customers and the read-only reporting endpoints.
customers:write	Create / update customers; capture leads.
deployments:read	Read deployments and rollout reporting.
deployments:write	Register / update deployments.
subscriptions:read	Read subscriptions.
subscriptions:write	Create subscriptions; record usage.
contacts:write	Add contacts and log interactions.

An unknown scope is rejected at creation (422).

Two capabilities are deliberately absent from the allowlist and can never be held by a token:

• Deletes — deleting a customer stays admin-interactive-only.
• Token management — minting or revoking tokens stays admin-interactive-only.

So a leaked token can neither destroy data nor mint more tokens. Its entire blast radius is the scopes you granted.

Note that read scopes bound reads too: a write-only token cannot read customer data. A token that carries only deployments:write can register a deployment but cannot list your customers.

Using a token

Send it as a bearer header on any /api/v1/* request:

export ATLAS_TOKEN="atlas_sk_…"   # from your secret manager

curl $ATLAS/api/v1/deployments?product=atlas \
  -H "Authorization: Bearer $ATLAS_TOKEN"

If the token is missing a required scope you get 403; if it is revoked or expired you get 401.

The security model

Every token is bounded on several axes at once:

• Scoped, not admin. A token holds an explicit scope set and can never reach a delete or token-management route.
• Revocable instantly. Revocation is checked on every request — revoke a token and the very next call is rejected. There is no session to expire.
• Expirable. Set expires_at and the token stops working after it, no action required.
• Attributable. Every write a token performs records an audit event naming the token — you can always see which token changed what, and when it was last used. The raw secret never appears in the audit trail, logs, or any read endpoint.
• Rate-limited. Each token has its own request rate limit; exceeding it returns 429, bounding how fast a leaked token could be abused.
• Stored hashed. Only a hash and a display prefix are stored. A database leak yields no usable tokens.

Operating tips

• Store the secret in a vault, never in source, argv, or environment files checked into git. It is shown once — capture it immediately.
• One token per job. Separate CI, agents, and scripts so you can revoke one without disturbing the others, and so the audit trail is legible.
• Scope minimally. If a job only reports deployment versions, give it deployments:read + deployments:write and nothing else.
• Set an expiry on tokens tied to a time-boxed task.
• Rotate on suspicion. Revoke and re-mint if a token may have leaked; revocation is immediate.

Getting help

Email support@seglamater.com for help wiring automation against Atlas, managed hosting, or consulting.