Tokens

Inspect Token

Return the namespace, grants, and expiry of the token used to authenticate the request.

GET https://rivet.example.com/auth/tokens/inspect

Examples

curl "https://rivet.example.com/auth/tokens/inspect" \
  -H "Authorization: Bearer $RIVET_TOKEN"

const endpoint = "https://api.rivet.dev";
const token = process.env.RIVET_TOKEN ?? "";

// Inspect reports on the token used to authenticate the request itself.
const response = await fetch(`${endpoint}/auth/tokens/inspect`, {
	headers: { Authorization: `Bearer ${token}` },
});

const { namespace_id, subject, grants, expires_ts } = await response.json();
console.log(namespace_id, subject, grants, new Date(expires_ts));

export {};

Authentication

Send the namespace token to inspect as a bearer token in the Authorization header. The admin token is rejected. See Authentication.

Responses

200

The token’s claims. The response carries Cache-Control: no-store.

Field	Type	Description
`namespace`	`string`	Namespace the token is scoped to.
`subject`	`string \| null`	Subject attached to the token, or `null`.
`grants`	`object[]`	Permissions the token carries.
`grants[].resource`	`"namespace" \| "actor" \| "node" \| "pool" \| "datacenter" \| "actor_gateway" \| "actor_kv"`	Resource type the grant applies to.
`grants[].target`	`"any" \| object`	`"any"` for every resource of this type, or `{ "id": "..." }` for one resource.
`grants[].operations`	`("read" \| "update" \| "list" \| "create" \| "delete")[]`	Operations the token may perform on the target.
`issued_ts`	`integer`	When the token was issued, in Unix milliseconds.
`expires_ts`	`integer`	When the token expires, in Unix milliseconds.

{
  "namespace": "my-namespace",
  "subject": null,
  "grants": [
    {
      "resource": "namespace",
      "target": "any",
      "operations": [
        "read"
      ]
    }
  ],
  "issued_ts": 1700000000000,
  "expires_ts": 1700000000000
}

401

auth.invalid_token: the request carries no token, the token is not valid, or it is the admin token rather than a JWT. auth.token_expired: the token has expired.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

500

core.internal_error: an unexpected failure. Details are only logged on the server.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "core",
  "code": "internal_error",
  "message": "An internal error occurred"
}

503

auth.verification_unavailable: token verification keys are temporarily unavailable. Retry the request.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "verification_unavailable",
  "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
}