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 API permissions and tunnel grants. API permissions decide which platform or engine actions the token can perform. Tunnel grants decide which tunnel projects the token can use and, when advanced scopes are present, which tunnel properties or HTTP paths are allowed.

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, and optional tunnel grants. 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 rstream control plane for every request.

The stored application credential can itself be limited with permissions and tunnel grants. 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 tunnelsGrants claim. The engine and API 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"],
      tunnelsGrants: [
        {
          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 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 tunnel grants, the auth token inherits them; a caller with unrestricted tunnel access may request new tunnel grants 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"],
    "tunnelsGrants": [
      {
        "projects": ["project-id"],
        "scopes": {
          "tunnels": {
            "create": {
              "filters": {
                "protocol": "http",
                "publish": true
              }
            }
          }
        }
      }
    ]
  }'

Permission categories

Account permissions cover sign-in, profile, workspace, project, billing, credential, and short-lived token APIs. Network permissions cover hosted API features around logs, rstream Auth, and TURN credentials. Tunnel permissions are enforced by the engine for live tunnel operations: tunnel creation and deletion, tunnel connections, and discovery of active runtime resources.

The important distinction is where enforcement happens. A token restricted to one tunnel project through tunnel grants can still call a 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 tunnel grants 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.