Access Tokens & Capabilities

Access tokens authenticate the CLI, Terraform, and API requests as a Bearer token. Every token carries a set of capabilities that bound what it can do. The stategraph user access-tokens commands let you mint, list, and revoke capability-scoped tokens directly from the CLI using an existing API key — no browser session required.

This is the recommended way to issue least-privilege credentials: a token can be limited to, for example, committing changes to a single state while being unable to manage users or create further tokens.

Capability Model

A token's capabilities are a subset of the capabilities held by the session that created it. A token can never exceed its creator.

Capability Grants Scope
admin Full access to everything. Global
commit Apply (commit) changes through transactions. Per-tenant and per-state
preview Plan (preview) changes through transactions. Per-tenant and per-state
users-manage Create, update, and delete users. Per-tenant
sudo Act on behalf of specific users. Per-user
access-token-create Issue new access tokens. Global
access-token-refresh Refresh existing access tokens. Global

When no capability flags are given, the token inherits the creating session's capabilities — the least-surprising default for "give me a token that can do what I can do."

stategraph user access-tokens create

Create an access token for the current user.

stategraph user access-tokens create --name <name> [capability flags]

The --name flag is required. The capability flags below select and scope what the token may do:

Flag Description
--admin Grant the admin capability (full access).
--commit Grant commit; unrestricted unless scoped with --commit-tenant or --commit-state.
--commit-tenant <uuid> Restrict commit to this tenant (repeatable).
--commit-state <STATE_ID=PATTERN> Restrict commit to resources in a state that match PATTERN (repeatable).
--preview Grant preview; unrestricted unless scoped with --preview-tenant or --preview-state.
--preview-tenant <uuid> Restrict preview to this tenant (repeatable).
--preview-state <STATE_ID=PATTERN> Restrict preview to resources in a state that match PATTERN (repeatable).
--users-manage Grant users-manage; unrestricted unless scoped with --users-manage-tenant.
--users-manage-tenant <uuid> Restrict users-manage to this tenant (repeatable).
--sudo-user <uuid> Grant sudo over this user id (repeatable).
--access-token-create Grant the access-token-create capability.
--access-token-refresh Grant the access-token-refresh capability.
--capabilities-json <json> Raw capabilities JSON object. Mutually exclusive with the individual capability flags above.

State patterns take the form STATE_ID=PATTERN. The pattern matches the directly modified resources in that state: use * for the whole state (for example sid=*), a prefix such as sid=module.foo.*, or a leading ! to deny.

Least-privilege example

Mint a token that can only commit changes to one specific state:

stategraph user access-tokens create \
  --name ci-prod-apply \
  --commit \
  --commit-state 'a1b2c3d4-5678-90ab-cdef-1234567890ab=*'

The token value is printed once in the response and cannot be retrieved again — store it securely.

field  value
-----  ------------------------------------
token  eyJhbGciOiJIUzI1NiIs...

For scripting, use --format json:

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

stategraph user access-tokens list

List the access tokens owned by the current user.

stategraph user access-tokens list

By default, output is a table with the columns id, name, created_at, expiration, owner_name, and owner_type. The expiration column is blank for tokens that never expire.

id                                    name           created_at            expiration  owner_name        owner_type
------------------------------------  -------------  --------------------  ----------  ----------------  ----------
f02791c8-aa63-4cdf-acae-a7c968d8a831  ci-prod-apply  2026-06-04T10:30:00Z              jane@example.com  user

For scripting, use --format json. Each token object also includes owner_id:

{
  "tokens": [
    {
      "id": "f02791c8-aa63-4cdf-acae-a7c968d8a831",
      "name": "ci-prod-apply",
      "created_at": "2026-06-04T10:30:00Z",
      "owner_id": "550e8400-e29b-41d4-a716-446655440000",
      "owner_name": "jane@example.com",
      "owner_type": "user"
    }
  ]
}

stategraph user access-tokens delete

Delete (revoke) an access token by id. The --token-id flag is required.

stategraph user access-tokens delete --token-id <uuid>

field    value
-------  ------------------------------------
id       f02791c8-aa63-4cdf-acae-a7c968d8a831
revoked  true

Inspecting your capabilities

Run stategraph user whoami to confirm the current identity and the exact capabilities a token or session holds. The capabilities object in its output mirrors the model above, so you can verify a least-privilege token is scoped the way you intended.

API

The CLI is a thin wrapper over three endpoints. See the API Reference for full details.

Method Endpoint Purpose
POST /api/v1/user/access-tokens Create a token. The request body accepts name and an optional capabilities object.
GET /api/v1/user/access-tokens List the current user's tokens.
POST /api/v1/user/access-tokens/revoke?token_id=<id> Revoke a token.

When capabilities is omitted from the create request, the token inherits the creator's full session capabilities; any requested capabilities are capped at the creator's, so a token can never exceed the identity that created it.

Next Steps