API authentication and scopes

Creating a token

In the client area, go to Settings → API tokens and create one. You’ll choose:

• A name. For you, so you can tell which one to revoke later. Names must be unique on your account.
• Scopes. What the token may do. Pick the narrowest set that works.
• An expiry, optionally — anywhere from 1 to 3650 days. No expiry means it lives until you revoke it.

The token is shown once, at creation. We store a SHA-256 hash and the public prefix, never the token itself. If you lose it, you revoke it and make a new one — we genuinely cannot recover it for you.

Token format

se_live_AbCdEfGhIjKl_<43 characters of secret>

64 characters, two fixed-width halves. The first 20 (se_live_ plus a 12-character prefix) are public — that’s what the client area shows you in the token list, and it’s how we find the right row without the secret. The rest is the secret.

Don’t split it on _ to parse it. The alphabet is base64url, which uses _ as a character, so about half of all secrets contain one. Split by position or don’t split at all.

Using it

Bearer auth, same as any other API — the envelope and status codes are the same on every route:

curl https://my.server.express/api/v1/cloud \
  -H "Authorization: Bearer se_live_AbCdEfGhIjKl_..."

Scopes

Twelve of them, deliberately coarse. A scope nobody understands is a scope nobody sets correctly.

The four marked ones are never granted by default, and the client area makes you confirm twice before it’ll mint a token holding them. A CI job that reads server status has no business being able to reinstall the box — or to order another one.

Wrong-scope errors

Calling an endpoint your token isn’t scoped for gives you a 403 that names the missing scope:

{
  "success": false,
  "error": "This token is missing the \"services:power\" scope."
}

Scopes are fixed at creation. Widening one means making a new token — a token can’t grant itself more power, which is the point.

Endpoints that don’t take tokens

Most of the API doesn’t accept tokens at all. That isn’t an oversight, it’s the default: an endpoint is unreachable by token until someone deliberately opts it in and names a scope. New routes ship closed.

Present a token to one of those and you get a 401 that says so, rather than a confusing “invalid token”:

{
  "success": false,
  "error": "This endpoint does not accept API tokens. Sign in from the client area."
}

The endpoint reference lists exactly what’s open.

Revoking

Revoke from the same settings page. It takes effect on the next request — there’s no cache to wait out.

Revoked and expired tokens fail with a message telling you which, because that’s nearly always your own stale config rather than an attack. Genuinely invalid tokens are treated as hostile and count toward an IP ban.

Keeping tokens safe

• Environment variables or a secrets manager. Not the repo.
• One token per system, so revoking one thing doesn’t break five others.
• Set an expiry on anything that isn’t permanent infrastructure.
• The token list shows last-used time and IP. Check it occasionally — a token that hasn’t been used in six months should be revoked.

Tokens carry your account’s authority. Anyone holding one can do everything its scopes allow.

Last updated Invalid Date. Something wrong or missing? Tell us and we'll fix it.