How to protect streams with token authorization by using the Wowza Streaming Cloud REST API

You can use the Wowza Streaming Cloud™ service REST API to restrict access to a stream by applying token authorization to a stream target. Token authorization allows only viewers who have the token, which is hashed and appended to the playback URL, to access the stream. You can use token authorization to make the stream playback URL unavailable after a certain length of time, to limit access to approved IP addresses, or apply other restrictions. A common use is to protect pay-per-view content to only paying viewers.

Contents


Add a Wowza CDN stream target for Apple HLS playback Create token authorization for the target Assign the stream target to a transcoder Generate the hashed token

Add a Wowza CDN stream target for Apple HLS playback


First, add a Wowza CDN stream target configured to play streams over Apple HLS or Apple HLS and Adobe HDS.

Stream target parameters

Parameter Data Type Description
name string A descriptive name for the stream target. Maximum 255 characters.
provider string Specify akamai_cupertino (for HLS-only playback) or akamai (for HLS and HDS playback).
type string Specify WowzaStreamTarget for a Wowza CDN destination.
use_cors Boolean (Optional) CORS, or cross-origin resource sharing, allows streams to be sent to providers such as Peer5, Viblast, and Streamroot, which implement a peer-to-peer grid delivery system. Specify true to enable CORS. The default is false. Available if the provider is akamai_cupertino.
use_secure_ingest Boolean (Optional) Specify true to deliver the HLS stream securely between the transcoder and the target. The default is false. Available if the provider is akamai_cupertino.

Example request and response

Note: In all code examples, for [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
The following request generates a Wowza CDN stream target for Apple HLS playback:
 
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "stream_target": {
     "name": "MyHLSTarget",
     "provider": "akamai_cupertino",
     "type": "WowzaStreamTarget"
   }
 }' "https://api.cloud.wowza.com/api/v1/stream_targets"
The details of the configured target are listed in the response, which should look something like this:
 
{
  "stream_target": {
    "chunk_size": "10",
    "created_at": "2016-02-23T16:04:23.170Z",
    "hls_playback_url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/[appname]/[streamname]/playlist.m3u8",
    "id": "1234abcd",
    "name": "MyHLSTarget",
    "primary_url": "http://[wowzasubdomain]-i.akamaihd.net/[appname]/[streamname]",
    "provider": "akamai_cupertino",
    "stream_name": "st1r2eam",
    "type": "WowzaStreamTarget",
    "updated_at": "2016-02-23T16:04:23.170Z",
    "use_cors": false,
    "use_secure_ingest": false
  }
}

Create token authorization for the target


Create token authorization for the Wowza CDN stream target.

Token authorization parameters

Parameter Data Type Description
enabled Boolean Specify true to permit token authorization for the target.
trusted_shared_secret string Provide a trusted shared secret for the token authorization. Must contain only hexadecimal characters and be an even number of characters equal to or less than 32.

Example request and response

The following request enables token authorization for the target 1234abcd:
 
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "token_auth": {
     "enabled": true,
     "trusted_shared_secret": "12345678abcdefgh"
   }
 }' "https://api.cloud.wowza.com/api/v1/stream_targets/1234abcd/token_auth"
The details of the configured authorization are listed in the response, which should look something like this:
 
{
  "token_auth": {
    "created_at": "2016-10-23T16:04:22.828Z",
    "enabled": true,
    "stream_target_id": "1234abcd",
    "trusted_shared_secret": "12345678abcdefgh",
    "updated_at": "2016-10-23T16:04:22.828Z"
  }
}

Related requests

View the details of a token authorization:
 
curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/stream_targets/[stream_target_id]/token_auth"
Update the token authorization applied to a stream target:
 
curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "token_auth": {
     "enabled": "false"
  }
 }' "https://api.cloud.wowza.com/api/v1/stream_targets/[stream_target_id]/token_auth"

Assign the stream target to a transcoder


Assign the token-authorized stream target to a transcoder's output rendition(s).
 
Note: For an adaptive bitrate transcoder, you must assign the target to all of the transcoder's output renditions.

Add stream target parameters

Parameter Data Type Description
id string The unique alphanumeric string that identifies the output rendition that will deliver content to the stream target. You can find the ID in the details of the output's transcoder.
stream_target_id string The unique alphanumeric string that identifies the stream target. You can find the ID in the details of the target you just created.
transcoder_id string The unique alphanumeric string that identifies the transcoder.

Example request and response

The following request adds the token-authorized stream target 1234abcd to the output rendition whose ID is 5678efgh for the transcoder 9012ijkl.
 
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "output_stream_target": {
     "stream_target_id": "1234abcd",
     "use_stream_target_backup_url": false
   }
 }' "https://api.cloud.wowza.com/api/v1/transcoders/9012ijkl/outputs/5678efgh/output_stream_targets/"
The details of the configured target are listed in the response, which should look something like this:
 
{
   "output_stream_target": {
    "stream_target_id": "1234abcd",
    "use_stream_target_backup_url": false
   }
}

Generate the hashed token


Once enabled, your playback URLs need to include the hdnts query parameter for playback to work. You can write a query in C, Java, PHP, Ruby, or other language. Download and experiment with these query code samples. Various parameters can be used along with the trusted_shared_secret. The following table includes a list of the basic parameters.
 
Note: All parameters are of the type string.
Parameter Description
algo The algorithm use to generate the token. Options are sha1, sha256 (the default), or md5.
end_time The time that protected access to the stream ends, in UTC seconds. For example, 1478995200 for 13 November 2016 00:00:00 GMT, 24 hours from start_time.
ip The IP address to restrict this token to.
key The trusted_shared_secret from Wowza Streaming Cloud required to generate the token. Using the example in this article, the value would be 12345678abcdefgh.
start_time The time that protected access to the stream begins, in UTC seconds. For example, 1478908800 for 12 November 2016 00:00:00 GMT. Use now for the current time.
 
Note: Go to epochconverter.com to convert human-readable time to UTC Unix timestamps.
token_name Parameter name for the token. The default is hdnts.
token_type Specify 2.0, 2.0.2, PV, or Debug.
url The Wowza Streaming Cloud playback URL, which is the hls_playback_url of the Wowza Streaming Cloud stream target. Using the example in this article, the value would be https://[wowzasubdomain]-i.akamaihd.net/hls/live/[appname]/[streamname]/playlist.m3u8.

Attach the hashed token to the URL of your stream using the format

[playback_URL]?[token_name]=[parameters_and_hashed_token]

For example, for an Apple HLS stream:

http://[wowzasubdomain]-i.akamaihd.net/hls/live/[appname]/[streamname]/playlist.m3u8?hdnts=exp=1461972009~acl=/*~hmac=de43455a65009cbb538495e5bc70c9565a3c559406c0c7bc2a1cfeaff9344706

For an Adobe HDS stream:

http://[wowzasubdomain].akamaihd.net/z/[streamname_angle]@[stream_id]/manifest.f4m?hdnts=exp=1461972009~acl=/*~hmac=de43455a65009cbb538495e5bc70c9565a3c559406c0c7bc2a1cfeaff9344706
 

If you're having problems or want to discuss this article, post in our forum.