Publish Tokens

Learn How to Create, Manage, and Delete Dolby.io Real-time Streaming Publishing Tokens

To broadcast a real-time stream the connection must be authenticated with a valid publish token. The Dolby.io platform uses token authentication for publishing to prevent unauthorized distribution of streaming content from your Dolby.io account. Without a valid token, publish requests will be rejected by the servers.

This guide outlines the following:

  1. How-to Create a Publish Token in the Streaming Dashboard
  2. How-to Manage Publish Tokens
  3. Deleting a Publish Token
  4. Using the Token REST API

📘

Subscribe Tokens

To restrict who may view a stream, you would use a separate subscribe token after enabling the Secure Viewer setting.

Create a publish token

Log into your Dolby.io Streaming Account and select Live Broadcast from the left menu. This is where you can view and manage all of your Publish tokens.

1590

Select the Create (+) button. This opens a pop-up window with options for configuring your new Publish token. Each option can be changed again later after the token has been created.

Basic settings

Let's go over each section in a bit more detail:

  • Token label gives you a naming system you can use to keep track of your tokens. You can use it to label what the tokens are used for by application, event, user or to differentiate testing from production use.
  • Record broadcast when enabled will allow you to record broadcasts using this token. After a broadcast is completed, you can find the recordings in the Recordings section of the dashboard. This is only available on paid plans. Review pricing details if you want to use this feature.
  • Secure viewer has two settings, "No Restrictions" (default) which allow anyone with the link to your viewer to watch a live broadcast without requiring authorization. The alternate setting, "Token Required", restricts your broadcast to only allow viewing the stream if provided a valid Subscribe Token.
  • Add stream names allows you to indicate how many broadcasts, called "Token Streams", you want to be managed by this Publishing token. A token can manage an unlimited number of streams as long as each has a unique alphanumeric name.
    • Create stream name allows you to specify a specific stream name such as "MainCameraFeed".
    • Create random stream names will generate a stream name dynamically to insure uniqueness, such as "hl7iqst".
    • Allow any stream name gives your token the ability to use ANY arbitrary stream name in the publishing path. The only rule to note here is that anyone using their own viewer must know what stream name the broadcaster is using in order to view the stream correctly.

🚧

Stream names are required to broadcast

To publish a stream, a stream name is required. Unless the Publish Token is set to Allow any stream name, the stream name must be equal to one of the created or generated stream names.

  • Temporary token allows you to specify an expiration date for the token. Click on the arrows above and below each section respectively, to set the expiration date. Once the date and time have passed, the token will automatically become invalid.
    • If a token expires in the middle of a broadcast, the broadcast will continue until the publisher ends it or if the Stop an active stream API is called for that token. The Temporary token feature prevents expired tokens from being able to start new streams, but doesn't impact already running streams.

👍

Temporary Publish tokens are recommended

Having an expiration date can prevent old or exposed tokens from becoming a long term vulnerability by limiting the duration they are valid. Tokens can always be deleted manually but if you know you only need the token for a set period of time it is more secure to create a token that is only valid for that duration.

Advanced settings

You will also see an Advanced tab at the top of the token creation interface; in this tab, you can configure more advanced settings.

  • Allowed Origins: If specified, only the domains listed will be allowed in requests to Director API. Wildcard subdomains are also allowed, such as "*.demo.com". When unspecified (empty), there are no domain restrictions.
  • IP Filter Type:
    • Allowed IP Addresses: Allows you to specify multiple IPv4 addresses or CIDR notated network blocks. If specified, the token will only be usable by those addresses.
    • Bind IPs on usage: If specified, Bind IPs on usage will bind the token to the first X IP addresses used with a token in requests to Director API, thus restricting the token to those IP addresses without them being known beforehand. Mutually exclusive with the AllowedIpAddresses option. Not currently supported with RTMP.
  • Cluster region: Specifies the cluster used for streaming. This setting is configured to use the default regional cluster set for the account. If Auto is selected, the regional cluster will be selected based on the publisher's location.
  • Geo-Blocking: Enables blocking by location at a country level for this specific Token.
  • Multisource: Enables streaming multiple feeds at once with one Publish token and Stream name combination, allowing for Multi-view playback.
  • Thumbnail previews: Enables previewing a thumbnail image of your video stream. Thumbnails are delivered via a webhook.

After you have successfully created your token, it will be displayed in a scrollable list.

1606

Once created, your Publish token can be used to broadcast in a variety of different ways using different hardware and software solutions. To learn more about how to broadcast with your Publish token, explore the Broadcast guide.

Managing and editing existing publish tokens

Once a Pubish token is created, it is displayed on the Live Broadcast page. From this page, you can start a broadcast using the Dashboard Broadcaster, enable or disable, delete, or edit the settings for each Publish token.

Even though the quick action menu provides you with a certain level of token control, the real control lies within the manage UI for each token. To open the manage view, simply click the Token Name on the item’s action menu. Once opened, you will see six tabs to explore.

1. Token details

The Token details tab allows you to view and edit settings specified during token creation. For a full list of these settings and their definitions, see Creating a Publishing token. The Token details page also includes the Publish token string and the Account ID string, which can both be copied and used for starting a broadcast.

1338

👍

Renew your token

If your token has been compromised you can renew it by clicking the renew button under the "Publishing token" string.

2. Token streams

As mentioned in Creating a Publish token, when a stream name is specified, it will require the user of the token to use a specific stream name in order to broadcast. Within the management view, you are able to add and delete stream names as you see fit.

To add a new name, simply click on the (+) CREATE button on the Token Streams tab, which will initiate a popup similar to the add token interface.

896

To delete a stream name, simply select it from the list and click the remove button.

3. Publishing

The publishing tab includes all information relating to broadcasting a stream with the Publish token. This tab can be broken down into four sections:

  • WHIP: The WHIP endpoint and Bearer token can be used to publish a WebRTC stream with WebRTC-compatible software and hardware.
  • RTMP: The RTMP/s publish paths and RTMP publish stream name can be used for publishing streams with RTMP-compatible software and hardware.
    • RTMP multi-bitrate can be enabled from this section. When enabled, the dashboard will create three RTMP publish stream names for low bitrate, medium bitrate, and high bitrate.
  • SRT: The SRT publish path, SRT stream ID, and SRT publish URL can be used for publishing with SRT-compatible software and hardware.
    • Passphrase encryption can be enabled from this section. When enabled, the dashboard will generate a passphrase for encrypting the SRT stream.
  • Publish token: The Publishing token and Stream name can be used to authenticate and start a broadcast from the Dolby.io Streaming Client SDKs or compatible software and hardware encoders.

To learn more about publishing and broadcasting with Dolby.io, check out the Broadcast guide, which provides more in-depth resources and examples on how to use the Publish token once it is created.

4. Playback

The Playback tab includes all relevant information for playing back a live stream. Dolby.io provides an out-of-the-box hosted player experience, which can be viewed at the Hoster player path URL or by embedding the Hosted embedded player as an <iframe> into your webpage.

From this tab, you can customize the player by altering settings such as the inclusion of the "Volume button" or if the stream is "Muted on start". To learn more about the hosted player or how you can build or use your own player, explore the Playback guide.

The playback tab also includes a WHEP endpoint. This can be used for devices that support WebRTC egress. To learn more about WHEP, explore the Playback section of the documentation.

5. Recordings

The Recordings tab can be used to view and download all recordings associated with this Publish token.

To learn more about recording, visit the Recordings guide.

6. API

The API tab includes information needed to publish a stream with the Client SDKs or from a third-party software or hardware source. The tab includes details in a few sections:

  • Publish token:
    • Publishing token: The Publishing token is a unique string that is required for authenticating a request to publish via the Dolbyio servers. This string should be protected and if exposed, should be cycled immediately to prevent unwanted broadcasts and charges.
    • Stream ID: The Stream ID is a combination of your Account ID and Stream name used for publishing or viewing the stream. If your stream is not secured with a subscribe token, you'll be able to view it at https://viewer.millicast.com?streamId=[Account ID]/[Stream name] when it is live.
    • Stream name: Your Stream name is used to manage and distinguish streams using the same token. You can edit the Stream name in the "Token streams" tab.
    • Account ID: The Account ID is a unique account identifier used for publishing and viewing streams.
    • Token ID: The Token ID can be used for Reading, Deleting, and Updating Publish tokens via the REST APIs.
  • Sample API calls: The Sample API calls section includes some basic examples of Publishing and Subscribing calls that can be made with the credentials provided in the Publish token section. To learn more about API calls, explore the Token API guide.
  • API endpoints: The API endpoints section provides a Publish API URL and a Subscribe API URL, which can be used with the Publish token credentials and Subscribe token credentials, respectively.

7. Multi-source

The multi-source builder is a tool to help you construct and configure publishing endpoint arguments to power a multi-view experience. You can add multiple SRT, RTMP, or WebRTC sources and can configure Multi-Bitrate publishing. The Multi-source tab also includes a URL to launch the hosted player in the multi-viewer configuration, customizable <iframe> code to add the hosted embedded player into your webpage, and the ability to export your multi-source file.

Deleting a token

Once you've finished using a Publish token, it is recommended that you retire the token by deleting it to prevent accidental vulnerabilities. Deleting the token can be done from the quick action menu found at the top-level Live Broadcast page by clicking on the trash can icon.

Using the Token API

This guide provides a high-level understanding of managing your tokens via the Dolby.io dashboard. Whilst the dashboard is a great choice for managing Publish and Subscribe tokens, all aspects of token creation and management can be programmatically controlled via the Dolby.io Streaming Token REST APIs. By utilizing the Token APIs to automate workflows, you can create scalable streaming solutions for your application or platform.

To learn more about using the REST APIs for token creation and management, check out: