Skip to main content
Sign In
Authentication

Scoped Tokens

Issue short-lived JWTs with explicit permissions in one namespace.

A scoped token gives its holder selected permissions in one namespace. Issue it on your backend with the control plane’s admin credential, then return only the scoped token to the application.

Quickstart

Issue a token

This example grants read access to Actor traffic in the production namespace. Every holder can reach every Actor in that namespace; use a specific Actor ID for private per-user access.

curl -X POST "$RIVET_API/auth/tokens" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "namespace": "production",
    "duration": 900,
    "grants": [
      {"resource":"actor_gateway","target":"any","operations":["read"]}
    ]
  }'

The response contains token, issued_ts, and expires_ts. Timestamps are Unix milliseconds; duration is seconds.

Use the token

Set $RIVET_TOKEN to the returned token and call an Actor’s gateway endpoint:

curl "$RIVET_API/gateway/$ACTOR_ID/health" \
  -H "Authorization: Bearer $RIVET_TOKEN"

This grant does not allow Actor creation, listing, node registration, or pool management.

Grants

Each grant names a resource, a target, and operations drawn from create, read, update, delete, and list. A target is "any" or an object such as {"id":"<actor-id>"}. Replace the placeholder with the resolved Actor ID.

ResourcePurpose
actorCreate, resolve, list, or manage Actors.
actor_gatewayReach an Actor’s actions, events, or HTTP handlers.
nodeRegister or inspect nodes.
poolRead or manage node pool configuration.

Actor management and gateway access require separate grants. Permission to reach one Actor does not allow the holder to create other Actors. Namespace administration and token issuance require the admin credential.

Inspect and renew

curl "$RIVET_API/auth/tokens/inspect" \
  -H "Authorization: Bearer $RIVET_TOKEN"

The response contains the namespace slug, grants, subject, and issue and expiry timestamps. Renew expiring credentials through your authenticated backend. Do not give clients the admin credential to renew tokens themselves.

Edit this page