Authentication & Authorization

The API.stream backend services rely heavily on modern JWT-based authentication flows. Our backend authentication service issues JWTs (herein referred to as "Access Tokens") which API clients assert on subsequent API calls. Those Access Tokens include grants allowing clients to safely share projects with collaborators and guests.

API.stream services, by design, do not provide an authentication system for end users of a partner's system. It is assumed our partners will implement an authentication service appropriate for their particular application and users. While the api.stream API services can ideally distinguish users from one another (for document ownership and authorization purposes), api.stream does not acquire, store, or have access to any personal information about the users of a partner's system. The user identifier associated with documents in api.stream's backend is an opaque string used for authorization.

From a Browser-Based Application

In a production workflow, users of a partner's system first connect to the partner's own backend for authentication. This flow may be inclusive of other third-party services (e.g., Google Firebase) on which the partner relies.

Once a partner's backend has authenticated a user of their system, the partner's backend system calls CreateAccessToken to obtain an Access Token on behalf of the user.

caution

This singular API call (CreateAccessToken) is the only api.stream API secured with a secret key (your "API Key"). As such, that API must only be called from a backend system where the secret key can be kept ... secret.

The newly minted Access Token is returned by the api.stream backend to the partner's backend, which in turn relays it to the partner's end-user client to complete the authentication flow. The client then initializes the api.stream SDK with the Access Token, or asserts it directly if using the APIs without an accompanying SDK.

From a Server Application

API usage from a server application is a simplified variant of the browser-based flow.

Development & Test Workflow

To help partners start working with the API quickly, we do permit developers to use their Development API Key in frontend applications (native or browser-based). In this workflow, a test application may use the Development API Key to call CreateAccessToken() to obtain an Access Token which can then be used for subsequent API calls. Note, however, that Access Tokens issued against the Development API Key are intentionally limited in capability, duration, and scope.

Permission Roles

When granting a user access token or a guest permission, you have the option to specify a role. The following matrix defines what each role correlates to.

Role	LiveAPI Read	LayoutAPI Read	Join WebRTC	LiveAPI Write	LayoutAPI Write	Invite Guests	Manage Broadcast	Start WebRTC
HOST	✅	✅	✅	✅	✅	✅	✅	✅
COHOST	✅	✅	✅	✅	✅	✅	✅	✅
CONTRIBUTOR	✅	✅	✅	✅	✅
GUEST	✅	✅	✅
VIEWER	✅	✅	✅