Authorization Module

Required Permissions: slobs.authorization

Minimum Version

This was module was added in Build 3 of the Streamlabs Desktop App Developer build.

The Authorization module allows your application to walk the user through a 3-legged OAuth flow with another service such as Twitch. This is facilitated by allowing your application show a sandboxed browser window that has the ability to navigate.

This system is designed to support both the Authorization Code Flow and the Implicit Code Flow offered by many OAuth providers. If you have your own backend server, we highly recommend using the Authorization Code Flow, as it allows you to refresh expired tokens, and is overall a more secure flow.

Your application has no control over this window other than the initial URL it loads. The URL must be whitelisted in your manifest, however, query parameters are ignored when matching the URL against the whitelist. At the end of the OAuth flow, the page should redirect to a URI with the protocol slobs-oauth://. Your app will receive an event when the page navigates to a slobs-oauth:// URI, and you can parse any credentials you need out of this URI. If you are using the Authorization Code Flow, your backend server should redirect to this URI when it is done. If you are using the Implicit Code Flow, the slobs-oauth:// URI can simply be your registered redirect URI with the OAuth provider.

This window is designed for facilitating 1-time authorization only, and should not be used to display UI for your application. This window uses a one-off browser session, and all cookies will be discarded when the window is closed.

Example

This example shows how to use the Authorization Module to perform the Implicit Code Flow with Twitch. Please note that URL https://id.twitch.tv/oauth2/authorize must be whitelisted in your manifest.json, and the redirect URI slobs-oauth://myapp must be registered with Twitch.

JavaScript

let loading = true;

streamlabsOBS.v1.Authorization.showAuthorizationWindow(
  'https://id.twitch.tv/oauth2/authorize?client_id=<your client id>&redirect_uri=slobs-oauth://myapp&response_type=token&scope=viewing_activity_read',
  {
    width: 600,
    height: 800
  },
  (event) => {
    if (event.type === 'auth_redirect') {
      // Pull tokens out of URI here
      console.log('Auth finished!', event.url);
    }

    if (event.type === 'close') {
      // If you didn't get an `auth_redirect` first, the window was closed
      // by the user before the authorization process was completed.
      console.log('Window was closed');
    }

    if (event.type === 'show') {
      loading = false;
    }
  }
);

AuthorizationWindowOptions object

An object with options for the authorization window

Property	Type	Description
width	number	The width of the window in pixels.
height	number	The height of the window in pixels.

AuthorizationWindowEvent object

This object describes an event emitted from the authorization window.

Property	Type	Description
type	auth_redirect | show | close	The type of event. See below for a detailed description of events.
url	string	This field will only be present on auth_redirect events, and contains the URL of the redirect. This can be used to parse any tokens resulting from the OAuth flow.

Here is a detailed description of each event type:

Event	Description
auth_redirect	This event will be emitted when the window redirects to a slobs-oauth:// protocol URI.
show	This event is emitted when the initial URL is loaded and the window is ready to show. For the best user experience, we recommend showing a spinner in your UI when the user clicks the authorization button. You can remove the spinner when this event is fired, which coincides with when the user actually sees the fully loaded authorization window.
close	This event will be emitted when the authorization window is closed for any reason including: - The user manually closing the window - Your application calling closeAuthorizationWindow - The window closing automatically when it has navigated to a slobs-oauth:// protocol URI

showAuthorizationWindow method

showAuthorizationWindow(url: string, options: AuthorizationWindowOptions, eventHandler: EventHandler): void

This method can be used to show a window to perform an OAuth flow.

Arguments

1. url: The URL to load in the authorization window. This URL must be whitelisted in your manifest.json. Query parameters are ignored for the purposes of matching.
2. options: A AuthorizationWindowOptions object containing options for the window.
3. eventHandler: A function that will be called with a AuthorizationWindowEvent object.

Returns

None

closeAuthorizationWindow method

closeAuthorizationWindow: void

This will close the authorization window for the current application. Note that this is usually not necessary, as the window will automatically close when it redirects to a slobs-oauth:// URI.