Tokens

Tokens are the primary authentication mechanism in rstream. They authenticate requests to the hosted APIs, connections to the engine, and HTTP requests when a published tunnel uses token authentication.

rstream has three token families: personal access tokens, application tokens, and auth tokens. Each family can carry Control plane API permissions, Engine API permissions, TURN permissions, and resource boundaries. Control plane API permissions decide which hosted account, workspace, project, credential, token, logs, rstream Auth, and TURN credential APIs the token can call. Engine API permissions decide which runtime tunnel actions the token can perform. TURN permissions decide whether the TURN runtime may allocate relay traffic. Resource boundaries live under resources.tunnels and narrow which projects, tunnel operations, labels, names, or HTTP paths the token can use.

Local configuration can store a token inline or, on macOS, as a Keychain reference. Hardened token and certificate storage options are documented in Credential Storage.

Personal access tokens

Personal access tokens are long-lived credentials created from the Dashboard or API. They are suited to automation, CI jobs, operators, and internal services that need a stable credential.

A personal access token can be created with full inherited permissions, a reduced permission set on each permission surface, and optional resource boundaries. The plaintext token is only visible at creation time. The stored credential can later be rotated, updated, or revoked.

Application credentials

Application credentials consist of a client id and a client secret. They are intended for backend integrations that should mint short-lived tokens on demand without calling the Control plane API for every request.

The stored application credential can itself be limited with permissions and resource boundaries. Every application token minted from it is then limited by those stored restrictions. An application token may also include a narrower permissions claim or a narrower resources claim. The engine, APIs, and TURN runtime keep the intersection, so a minted token cannot exceed the stored application credential.

This pattern is useful for remote devices. A backend keeps the client secret, then issues a one-minute token that can create tunnels for one project but cannot manage account resources or connect back to other tunnels.

import { createClientCredentialsToken } from "@rstreamlabs/rstream";
const { token } = createClientCredentialsToken(
  {
    clientId: process.env.RSTREAM_CLIENT_ID!,
    clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
  },
  {
    expiresInSeconds: 60,
    claims: {
      permissions: ["tunnels.tunnels.create-delete"],
      resources: {
        tunnels: {
          projects: ["project-id"],
          scopes: {
            tunnels: {
              create: {
                filters: {
                  protocol: "http",
                  publish: true,
                  token_auth: true,
                },
              },
            },
          },
        },
      },
    },
  },
);

Auth tokens

Auth tokens are short-lived tokens created through the API. They are not stored as credentials. Their practical use is delegation: a backend, browser session, or service with token creation rights asks the Control plane API to mint a temporary token for a narrower task.

Auth tokens inherit the caller boundaries. Passing permissions: null keeps the caller permissions. Passing an explicit permission array reduces them. If the caller already has resource boundaries, the auth token inherits them; a caller with unrestricted project access may request new resources.tunnels boundaries for the minted token.

curl -X POST "https://rstream.io/api/tokens" \
  -H "Authorization: Bearer <pat-or-app-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["tunnels.tunnels.create-delete"],
    "resources": {
      "tunnels": {
        "projects": ["project-id"],
        "scopes": {
          "tunnels": {
            "create": {
              "filters": {
                "protocol": "http",
                "publish": true
              }
            }
          }
        }
      }
    }
  }'

Permission categories

Control plane API permissions cover hosted actions such as sign-in, profile, workspace, project, billing, credential, token minting, logs, rstream Auth, and managed TURN credential APIs. Engine API permissions are enforced by the engine for live runtime operations: tunnel creation and deletion, tunnel connections, and discovery of active tunnel state. TURN permissions are enforced by the TURN runtime for relay allocation.

The important distinction is where enforcement happens. A token restricted to one project through resources.tunnels can still call the Control plane API if it also has the relevant API permission. Conversely, a token with no tunnel permission cannot create or connect to tunnels even if it can read project metadata from the hosted API.

Reduction model

Permissions and resource boundaries are reduced as tokens are derived. Stored credential permissions limit PATs and application credentials. Claims inside minted tokens can only reduce that authority further. Project settings can add project-wide runtime requirements such as authenticated public access, trusted IPs, GeoIP restrictions, and a minimum TLS version.

The resulting model is conservative: the most restrictive applicable boundary wins. A backend can safely issue short-lived tokens to remote devices or tenants without giving them the full authority of the stored credential.