SextantDocs
v2.4latest
v2.4latestv1.9legacy

Switching keeps you on the same page when it exists in the other version.

On this page

Tokens and scopes

Create API tokens with the smallest scopes that work, set expiries, rotate them without downtime and revoke them.

Updated Guides Version v2.4

Every request to the API carries a bearer token. A token has a name, a set of scopes and an optional expiry. The secret is shown once, when you create the token.

Shell
sextant tokens create --name ci-deploy --scope jobs:write --scope jobs:read --expires-in 90d
Text
id         tok_71c0de
secret     sxt_live_71c0de5a8e3b4f19a6d2c07be1f45a90   (shown once)
scopes     jobs:read jobs:write
expires    2027-01-18

Scopes

Scopes follow the pattern resource:action. A token can only call endpoints whose scope it holds.

Scope Allows
jobs:read List and retrieve jobs
jobs:write Create, cancel and retry jobs
schedules:read, schedules:write Read, or also change, schedules
queues:read, queues:write Read queue state, or also pause and resume
workers:read List workers
webhooks:read, webhooks:write Read, or also manage, webhooks
admin Everything, including creating tokens

Token prefixes

sxt_live_ tokens work against a production server. sxt_test_ tokens are created by servers with server.mode = "development" and are refused by production servers, so a test token cannot leak into the wrong environment and succeed.

Rotate without downtime

  1. Create the new token with the same scopes.
  2. Deploy it to the service that uses it.
  3. Watch the old token’s last_used_at stop moving (sextant tokens list).
  4. Revoke the old one.
Shell
sextant tokens list
sextant tokens revoke tok_9a41f0

A revoked token fails at once with 401.

Where to keep tokens

Put them in your platform’s secret store and pass them as the environment variable SEXTANT_TOKEN; the CLI and every SDK read it by default. Do not put them in sextant.toml, in a container image or in a repository.

See the API overview for how tokens are sent and what a 401 or 403 looks like.