Fine-Grained Tokens

Fine-grained tokens extend the token model with scopes that precisely describe what a token can do. The goal is to allow rstream to operate safely in environments where clients and upstream services are not fully trusted, while still enabling dynamic discovery and real-time connectivity.

Scopes can restrict tunnel creation, tunnel listing, and tunnel connections. For HTTP tunnels, connection scopes can also restrict request paths.

In the JavaScript SDK schema, fine-grained scopes are carried in metadata.scopes on a token payload.

Scope structure

The current scope model includes a tunnels root with optional create, connect, and list scopes. Each scope can be a boolean or an object form.

Filters support logical composition and operators such as exact match, one-of lists, and regular expressions.

Example

The example below mints a short-lived token that restricts tunnel creation to HTTP tunnels, restricts connections to paths matching ^/api, and restricts listing to a selected set of tunnel fields.

const { token } = await client.auth.createAuthToken({
  expires_in: 60,
  scopes: {
    tunnels: {
      create: { filters: { protocol: { oneof: ["http"] } } },
      connect: { params: { path: { regex: "^/api" } } },
      list: { select: { id: true, name: true, protocol: true } },
    },
  },
});