Token API
How to manage the publish and subscribe Tokens with the REST API
Dolby.io Real-time Streaming provides you with a RESTful API that allows you to control your Dolby.io Real-time Streaming service securely from within your application, without the requirement of using the Dolby.io dashboard. The API enables you to manage features such as your Stream Tokens which are required to create live broadcast streams. Once you have securely authenticated with the API, you can create a new stream, delete it, update it and more.
The PublishToken REST APIs let you create, manage, and delete your tokens.
Acquiring Your API Token
In order to interface with our API you must first create an API Secret to be verified as a user, otherwise all API calls will be rejected.
To acquire an API Secret, log into the Dolby.io dashboard, and click on "Settings" in the left-side menu.
Navigate to the Security tab and click the add icon to add an API Secret. Then you select it from the field, and copy and paste it into your code accordingly.
Once you have created your initial API Secret, you can use the same edit button to refresh the API Secret, and any further access using old tokens will then be rejected. You can also delete the token and disallow ALL API access to your account as it was by default when you first signed up.
Managing Stream Tokens
The Dolby.io Real-time Streaming stream tokens publishing and subscribing, allow you to create individually secured streams which include a simple set of rules. For example, you can create a publishing token that only allows the use of a single stream name, which your publishing client MUST use when broadcasting, otherwise it will be rejected. In addition, if anyone attempts to broadcast with the same stream name while it is already in use, this will also be rejected.
Publishing Tokens
Here is an example using CURL to create a publishing token. Alternatively you can also use a middle layer (such as Nodejs) to securely call the Dolby.io Real-time Streaming without exposing your token publicly.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/publish_token \
-d '{"label": "MyLiveFeed", "streams": [{"streamName": "feed1"}]}'
Where your_api_secret is the token you got from Account > Security > API Secret, MyLiveFeed is an arbitrary label, and feed1 is the stream name which you have assigned.
Alternatively you can add additional stream names to allow for more than 1, or even a wildcard ( .* ) to allow use of any arbitrary stream name.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/publish_token \
-d '{"label": "MyLiveFeed", "streams": [{"streamName": "feed1"}, {"streamName": "feed2"}, {"streamName": "feed3"}]}'
With wildcard:
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/publish_token \
-d '{"label": "MyLiveFeed", "streams": [{"streamName": ".*", "isRegex": true}, ]}'
Subscribe Tokens
Unlike the publisher, the subscriber (viewer) by default, does not need a token to view a broadcast. However if you wanted to secure your feed from being viewed by any prying eyes using a subscribe token would be the way to go.
Similar to the publishing token the subscribing token has its own set of rules you can use to protect your feed. You can create a token with a time limit, or set the token to work from a single or multiple specified domains. Or you can even set it to use a specific IP or IPs as well. You can learn more about these features below.
Like the publishing token we can easily create a subscribing token with a simple API call. Here is an example:
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token \
-d '{"label": "MyLiveViewer", "streams": [{"streamName": "feed1"}]}'
You will need the API secret explained above to do a successful query of this API call.
This subscribe token is set up to simply mirror the publishing one we created above to only allow the specified stream name to be viewed, all other stream names are blocked by the token rule. You can make different rules and have many subscribe tokens for 1 feed. Alternatively you can have multiple publishing tokens with 1 subscribing token as well.
You can fully restrict the broadcast to only allow viewing connections that have a valid subscribing token. You can achieve this by updating the publishing token's "subscribeRequiresAuth" boolean setting. By default this is set to false, this allows unrestricted subscribers to view the feed even if some subscribers have a token. By setting this to true the viewer can only successfully connect if there is a valid subscription token.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/publish_token/[token id] \
-X PUT -d '{"subscribeRequiresAuth": true}'
Update where [token id] is replaced with the id of the publishing token in question, and subscribeRequiresAuth is set to true. You can find your token id in the result object when you created your publishing token, or you can find it in your Dolby.io dashboard account under the tokens API details, or can do a List Tokens call from the API (see List Tokens).
Note: By restricting the publishing token to use a subscription token only, you might experience some rejections with the hosted Millicast viewer. Fortunately the hosted Millicast viewer has an unsecure url parameter option called "token" that you can use to satisfy the token requirement. To use it you simply add the parameter to the iFrame or in the URL following the stream id, here is an example:
https://viewer.millicast.com/?streamId=accountId/streamName&token=yourtokenid
You simply add your subscription token to the token parameter and the hosted Millicast viewer will do the rest. Below are other features that you can use with your tokens that can help you secure your broadcast experience with Dolby.io Real-time Streaming.
Note: Subscribe tokens are optional to your broadcast, they are meant to help give you more control over the security of your stream and your viewers.
Listening to Events
Currently, the API will block a connection to viewers that have no token and attempt to play a feed that does not exist or is not currently live. Using a simple viewing token like we created above will allow a user to bypass this security feature and stay connected while it waits for the live stream to begin.
To assist the developer, the broadcasting websocket will dispatch events notifying the client whenever the live stream begins or ends, allowing the developer to create notices and transitions to guide the viewer on what is happening with the feed. See Broadcast Events in the Web Tutorial to learn how to do this.
Domain Restricting (allowedOrigins)
Tokens can restrict your publishers and subscribers to only be allowed to broadcast or view from your website. Both publisher and subscriber tokens allow you to set this rule with an array called "allowedOrigins". This array expects a list of string values, representing the domains and or subdomains, in which to restrict where a user publishes from and or where a user views from.
If a domain is specified on the list, you will not be able to connect to the service unless you are connecting from that domain specifically. For example, if you set a publish token allowedOrigins setting to list your domain only, then any publishing that is done absolutely must come from that specific domain or website.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token \
-d '{"label": "MyLiveViewer", "streams": [{"streamName": "feed1"}], "allowedOrigins": ["mydomain.com"]}'
With that said, if you were then to go to your account on Dolby.io Real-time Streaming and try the broadcaster from your dashboard account, the connection would fail because it is hosted from millicast.com and not the domain you restricted the token to. You would need to update your publish token and add millicast.com as an additional domain to your list of allowedOrigins in order for the hosted Millicast Broadcaster to work.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token/[token id] \
-X PUT -d '{"allowedOrigins": ["millicast.com","*.millicast.com","mydomain.com"]}'
Note: Support for wildcard subdomains is allowed. Ex: *.millicast.com
To do an update to an existing token remember to update [token id] with your subscriber token's id. You can find this ID in the result object when you first create your subscribe token or from the List Tokens call in the API.
Note: When listing your tokens it can be difficult to tell which is which, using the Label property when creating tokens helps to manage that. Ex: "label": "My Test Token 1" or use any arbitrary label that will help you correctly target the right token.
If you want to remove this restriction and default it to allow all domains, you can simply do updateAllowedOrigins setting with an empty array. This will default to allow users to view and broadcast from all domains again with the token.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token/[token id] \
-X PUT -d '{"allowedOrigins": []}'
Alternatively you can also create a new publishing token without the list and use both tokens for different situations, 1 for a more restricted broadcast, and the other token for a less restricted one. This will also work with the subscribing token as well.
Note: This is an optional feature and is not supported with the RTMP service.
Restricting IPs (allowedIpAddresses)
Like domain restricting, you can apply rules to your publish and subscribe tokens that let you restrict a broadcaster or a viewer to only connect if the situation meets the right criteria. In this case we are looking for a specific IP or IPs to be allowed. For example, if a developer wanted to allow only a specific person or persons to broadcast or view, all they would need to do is specify the publisher or viewer's IP address in an array property called "allowedIpAddresses". This would restrict the broadcaster or viewer from sharing the access from another IP outside their network.
Note: To fully restrict these settings, make sure you set the publishing token's subscribeRequiresAuth setting to true so the viewer MUST have a valid subscription token before viewing. Any connection attempt without a valid token will be rejected.
With the IPs set the user can only broadcast or view from that IP or network. If the user with the allowed IP changes their network resulting in a different IP they will of course be rejected. However you can easily replace the IP in the token or include the new IP with a simple update call.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token/[token id] \
-X PUT -d '{"updateAllowedIpAddresses": ["255.255.255.255"]}'
Like the allowedOrigins feature, to clear out the IPs you can do another call to updateAllowedIpAddresses with a blank array for no IP restrictions.
Note: This is an optional feature and is not supported with the RTMP service.
Binding to an IP (bindIpsOnUsage)
Binding an IP works in conjunction with the allowedIpAddresses setting and like its counterpart it will restrict the token to only allow the user that matches the IP address to publish or subscribe respectfully. However different than the allowedIpAddress feature the bindIpsOnUsage sets the IP/s of the first user or users that actively use it when authenticating. This is useful when you do not know the users IP address ahead of time. The token will record that first user/s IP and set it to the allowedIpAddresses list after a successful first query, binding it to the users IP address and restricting any other user that does not match that address rule.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token \
-d '{"bindIpsOnUsage": 1}'
For example if a broadcasting client wanted to share their viewer to a specific person without allowing that person to re-share that same viewer link with others, the broadcaster can set the bindIpsOnUsage setting to 1 which will tell the API to restrict the token to the first user that queries the API with this token (if the broadcasting user sets a 2 it will bind to the first 2 IP's and so on).
Unlike a first time use token where the token is nullified after the first person uses it, this method allows a user to refresh the link and still be allowed to watch or broadcast without having to re-create a new token.
To revert the token to the default settings you can update the token and set 0 to the bindIpsOnUsage and set an empty array on its counterpart allowedIpAddress list to remove any IP's that have been recorded.
curl -H "Authorization: Bearer [your_api_secret]" \
-H "Content-Type: application/json" \
https://api.millicast.com/api/subscribe_token/100 \
-X PUT -d '{"bindIpsOnUsage": 0, "updateAllowedIpAddresses": []}'
Now your token is no longer bound to any IP's.
Note: This is an optional feature and is not supported with the RTMP service.
To see more Dolby.io Real-time Streaming examples click here.
The Dolby.io Real-time Streaming service will be updated often as our service evolves, so please check back periodically for updates.
Updated about 2 months ago