Skip to main content

Tokens and Scopes

How Native Frame decides who may broadcast, watch, or manage a stream — through short-lived, scoped access tokens rather than long-lived secrets.

Every request to the platform is authenticated with a JSON Web Token (JWT). The token is signed by you and carries the scopes that determine what its holder is allowed to do. This page explains what a token represents and what scopes are; when you are ready to mint one, follow the how-to at Get your first token.

Why the model exists​

You never want to ship a long-lived, all-powerful secret to a browser or mobile app, where anyone can read it. Instead, your backend holds the signing key and mints a short-lived token scoped to one user and one job — a viewer token that can only watch, a broadcaster token that can only publish. If a token leaks, it expires quickly and can do only the narrow thing it was scoped for. This is the same access-token pattern used across real-time video platforms.

What a token represents​

A token is a JWT your backend signs with a JSON Web Key (JWK). Beyond the standard JWT fields, it carries:

  • Scopes — the roles the holder may act in (see below).
  • A user identity — the userId the token represents.
  • A lifetime — a ttl, so the token expires on its own. User tokens are deliberately short-lived, typically minutes to hours.

There are two kinds of token, for two different callers:

  • Service-account tokens authenticate your backend to the platform for server-to-server work — provisioning and managing resources. They carry the service-account role.
  • User-based tokens authenticate an individual end-user in a client application — a viewer watching or a broadcaster publishing. They carry video scopes and are the tokens you hand to the browser or app.

What scopes are​

A scope names the role the token holder plays, and the platform checks it on every operation. Using a viewer token to broadcast fails with a permission error, by design. Scopes fall into a few groups:

  • Streaming — broadcaster and viewer for public streams, and private-broadcaster and private-viewer for private ones.
  • Group calls — conference-owner for the host who manages the call, and conference-participant for attendees.
  • Backend and management — the service-account role for server-to-server calls, plus Cloud API permission scopes such as prm:MANAGE_PROGRAM that gate program-management endpoints.

The scope also encodes limits — for example, a private-broadcaster allows a single producer, and a conference-owner call allows up to ten producers. The scope reference documents the streaming scopes (broadcaster, private-broadcaster, viewer, private-viewer) in more detail; the conference, service-account, and permission scopes described above are not yet in that reference.

Next steps​

See also​