API tokens & REST

Creating tokens

stn token "ci read-only"                              # create a scoped read token (shown once)
stn token "dashboards" --scope decisions:read --scope entries:read
stn tokens                                            # list your tokens (prefixes only)

Scoped tokens are read-only. Two scopes are allowed — decisions:read and entries:read (the default is both); any other scope is rejected at creation. The raw token (prefixed stp_live_) is shown exactly once, so copy it then. There's a per-user cap on live tokens; revoke one to free a slot. List your tokens with stn tokens (you see prefixes and scopes, never the secret); revoke from the web dashboard.

The REST endpoints

Use the token as a bearer credential against the programmatic read endpoints, mounted under /api:

curl -H "Authorization: Bearer <token>" \
  "https://stndp.io/api/v1/api/search?q=retry+policy"

# also available:
#   GET /api/v1/api/decisions
#   GET /api/v1/api/graph/neighbors?type=decision&id=42

These return the same JSON the corresponding CLI commands render — restricted to what your token's read scope authorizes and to what the token's owner can see. A request whose scope doesn't cover the data is rejected, so a decisions:read-only token can't read entries.

Inbound vs. outbound

These tokens are for reading out of stndp. To push events in — e.g. a CI failure that opens a block — use a signed inbound webhook instead.