Tokens

Create Token

Issue a scoped token. Use this to mint short-lived tokens that grant a client access to a single actor instead of sharing your namespace token.

Each grant names a resource type, a target ("any" or a specific { "id": ... }), and the operations it allows. The RivetKit client wraps this as handle.issueToken().

POST https://api.rivet.dev/auth/tokens

Examples

curl -X POST "https://api.rivet.dev/auth/tokens" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "my-namespace",
    "subject": "user-123",
    "duration": 3600,
    "grants": [
      {
        "resource": "actor_gateway",
        "target": {
          "id": "00000000-0000-0000-0000-000000000000"
        },
        "operations": [
          "read"
        ]
      }
    ]
  }'

import { createClient } from "rivetkit/client";
import type { registry } from "./index";

const client = createClient<typeof registry>(process.env.RIVET_ENDPOINT);

const counter = client.counter.getOrCreate(["my-counter"]);

// issueToken() resolves the actor ID and sends POST /auth/tokens with a
// grant scoped to this actor. It defaults to actor_gateway read access.
// expiresIn is in seconds.
const { token, expiresAt } = await counter.issueToken({
	subject: "user-123",
	expiresIn: 60 * 60,
});

// Hand the token to a browser client. It can only reach this actor.
console.log(token, new Date(expiresAt));

Authentication

Send your namespace token as a bearer token in the Authorization header. Every control plane request also requires the namespace query parameter. See Authentication.

Request Body

Content type: application/json.

Field	Type	Required	Description
`duration`	`integer \| null`	No	Lifetime in seconds. Omit for the default lifetime.
`grants`	`object[]`	Yes	Permissions the token carries.
`grants[].operations`	`("read" \| "update" \| "list" \| "create" \| "delete")[]`	Yes	Operations the token may perform on the target.
`grants[].resource`	`"namespace" \| "actor" \| "runner" \| "runner_config" \| "datacenter" \| "actor_gateway" \| "actor_kv"`	Yes	Resource type the grant applies to.
`grants[].target`	`"any" \| object`	Yes	`"any"` for every resource of this type, or `{ "id": "..." }` for one resource.
`namespace`	`string`	Yes	Namespace the token is valid in.
`subject`	`string \| null`	No	Free-form subject to attach to the token, such as a user ID.

Responses

200

Field	Type	Description
`expires_ts`	`integer`	When the token expires, in Unix milliseconds.
`issued_ts`	`integer`	When the token was issued, in Unix milliseconds.
`token`	`string`	The issued token. Treat it as a secret.

{
  "expires_ts": 1700000000000,
  "issued_ts": 1700000000000,
  "token": "sk_..."
}