It is best practice to generate new streaming tokens whenever we are working with new applications using Dolby.io Streaming. Whether it is about distributing streams to different groups, giving different privileges to different regions, or simply separating entire projects, it is important to use unique tokens to prevent accidental leaked credentials affecting as large a body of users as possible. The issue then becomes translating this to scale; going to the dashboard to generate a new token by clicking every time simply isn’t a viable option when done en masse.
To solve this issue, we can turn to using API calls to programmatically generate new Publish and Subscribe Tokens as needed with our REST API. These can be functions that take a fraction of a second to run, and can be called at any time, creating a fresh, secure authentication token for you to start broadcasting to immediately. In this post, we will demonstrate how to use and interact with this API using Postman, a free tool that helps visualize what an API call looks like beyond raw code. The behavior is most similar to using a cURL script, however any programming language that is able to make an HTTP request should be able to interface with the Dolby.io REST API.
This has an application in many different industries. For example, say you run a sports broadcasting network, and need to create a new stream for every game that happens. While some tokens may be reused, often times there are multiple different broadcasts that happen simultaneously, where we would want to generate a new token for each simultaneous broadcast that is started to avoid downtimes. This can be solved by generating new publish tokens programmatically with the REST API. Let’s see how it works.
Prerequisites
Before we get started, it is important that we have a couple of things in place. The first is a Dolby.io account, which you can sign up for free and receive $50 of free credit to tinker with.
Additionally, we will want to download the Postman desktop application. While Postman does have a web interface, we have found that the desktop version tends to have a smoother experience with this use case.
Obtaining your Dolby.io Streaming API Credentials
To start using our REST API, we need to obtain the unique API secret we will use to authenticate all of our API calls, and associate them to our account. To do this, ensure that you are on the “Streaming” section of the dashboard:
Then navigate to “Settings” on the sidebar:
You should now see a field titled “API Secret”. Be sure to keep this value private, as anybody who has it will be able to call API requests on your behalf.
If you ever need to change your API secret due to a leak or change of administration, you can click the pencil button to the right, and refresh your API Secret. *Note however that this will break any existing scripts or code that uses your old API secret, so don’t forget to update and secure it!
Using the Postman Streaming API Collection
For ease of use, we have created a Postman collection containing all of the Dolby.io Streaming API credentials prebuilt for use. This means all we need to do is change a couple of variables before we can get started making API calls!
To begin, we will see the Collections tab of the collection. This will be where we perform most of our API calls, but first we need to set a few variables first.
Navigate to “Environments” on the left side bar and select “Streaming-API-Sample”. In the field designated by the row “api-secret” and column “CURRENT VALUE”, paste in the API Secret we collected from the Dolby.io Streaming dashboard earlier, and save using “Cmd/Ctl + S” on your keyboard. This will save our API credentials to our current session without saving it to the entire world to see.
Next, let’s navigate back to the “Collections” tab and navigate to “PublishToken”. This will open a few different endpoints, which can all be read about in further detail at our API documentation. For this example, we will work with “Create Token”.
This screen now contains the logic of our API endpoint. We have already preconfigured all of the headers, and URL endpoints, so the only thing we need to modify lives in the “Body” section.
We can read about what exactly all these parameters do in our API reference, but the two key variables to change are label and streamName. These will help differentiate this token with all of the other tokens you have created, so label it something relevant. While we could fork and modify this endpoint directly, in Postman we can set values to these variables within the environment. To do this, click on the “PublishToken” folder again and select the “Variables” tab, where we can add “Current Values” under label and streamName. Remember to save once more.
Now, we can navigate back one last time to the “Create Token” endpoint and click “Send” on the top right. This will send our API request and if all steps were performed successfully, a body will pop up on the bottom with the response content.
To confirm that this token was properly created by navigating back to our Dolby.io Streaming Dashboard, where we can find the token we just created under the “Live Broadcast” tab.
Additional API Applications
Now that we know how to use the Publish Token Create API endpoint, we can apply the same principles to other API endpoints.
For example, in our sports broadcasting scenario, say certain sports streams needed to be region locked to specific parts of the world due to licensing agreements. We can create a Subscribe Token that includes the region blocking parameters all in a single API call that will limit the viewers at will.
There are similar endpoints for Updating, Deleting, and Listing all existing tokens among others that can be helpful in managing larger scale broadcast networks. We often see many of them combined together in successful workflows to manage stream networking as a whole.
Finally, remember that these APIs are not locked to Postman or CURL. If you are using another language in your system, chances are it can interact with our API. Review our API documentation to learn how to use it in your environment.
Conclusions
When thinking about the REST API, it is important to think about how it will be used effectively. Creating tokens manually in the dashboard is fine as long as it is done at a small scale at sparse intervals, but as soon as it becomes a common trend, API automation becomes invaluable.
Remember to keep your token management system secure at all times, as anyone with your token can reasonably stream from it. To learn more, read this blog on securing token authentication.
If you run into questions, don’t hesitate to reach out to our support team for help. Good luck!
