Manage user authentication for HLS streams with the Wowza Video REST API

Live stream workflow

1. Create a live stream

Create a live stream with a push connection and user authentication by sending a POST request to the /live_streams endpoint.

You can use the following sample request, making sure to:

• Set encoder to the type of encoder that you are using. When you create a live stream with a push connection over RTMP or RTSP, user authentication is required by default. You don't have to configure any parameters to enable it.
• Set broadcast_location to the region that's closest to your video source.
• If you need to disable authentication, set disable_authentication to true .
• Consider configuring your own username and password values for authentication. The username and password values are case-sensitive and can only contain alphanumeric, period (.), underscore ( _ ), and hyphen (-) characters. If you don't include them in your request to create the live stream, Wowza Video will assign username and password values for you and return them in the response.
• Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{ 
 "live_stream": { 
  "aspect_ratio_height": 1080, 
  "aspect_ratio_width": 1920, 
  "billing_mode": "pay_as_you_go", 
  "broadcast_location": "us_west_oregon", 
  "encoder": "other_rtmp", 
  "name": "User authenticated live stream", 
  "transcoder_type": "transcoded", 
  "delivery_method": "push", 
  "hosted_page": {
    "enabled": true, 
    "page_title": "My Hosted Page"
     }
  "password": "abcPassword", 
  "player": {
    "responsive": true, 
    "type": "wowza_player"
     }
  "username": "clientABC" 
 } 
}' 

"${WV_HOST}/api/${WV_VERSION}/live_streams" 

Sample response

The response includes:

• An ID for the live stream that you'll use in step 3.
• source_connection_information you'll use in the next step to configure a source encoder for the live stream.
  • primary_server , host_port , application , stream_name , username , and password .

{ 
  "live_stream": { 
    "id": "8bwzg5vj", 
    "name": "User authenticated live stream", 
    "transcoder_type": "transcoded", 
    "billing_mode": "pay_as_you_go", 
    "broadcast_location": "us_west_california", 
    ... 
    "encoder": "other_rtmp", 
    "delivery_method": "push", 
    "target_delivery_protocol": "hls-https", 
    ...
    "source_connection_information": { 
      "primary_server": "rtmp://[wowzasubdomain].entrypoint.cloud.wowza.com/app-1670", 
      "host_port": 1935, 
      "stream_name": "b6232dcb", 
      "disable_authentication": false, 
      "username": "clientABC", 
      "password": "abcPassword" 
    }, 
    "player": {
      "id": "zxn5prrj", 
      "type": "wowza_player", 
      ...
      "embed_code": "in_progress", 
      "hls_playback_url": "https://[subdomain].wowza.com/[stream_id]/[stream_name]/hls/live/playlist.m3u8"
         }
    "hosted_page": {
      "enabled": true, 
        ...
         }
    "stream_targets": [ 
      { 
        "id": "bnlbnb8p" 
      } 
    ], 
    "direct_playback_urls": { 
      "rtmp": ["names, output_ids, and urls returned here"], 
      "rtsp": ["names, output_ids, and urls returned here"], 
      "wowz": ["names, output_ids, and urls returned here"] 
    }, 
    "created_at": "2018-08-03T18:57:59.000Z", 
    "updated_at": "2018-08-03T18:57:59.000Z", 
  } 
} 

2. Configure a source

Use the source_connection_information from the live stream response to configure your RTMP encoder. You'll need to refer to documentation for your specific encoder to determine where to input the source_connection_information settings, which include the stream and user credentials for authentication.

If you were configuring OBS as the encoder, you'd enter the following stream settings in OBS:

• URL is formatted as:
  rtmp:// [ primary_server ] : [ host_port ] / [ application ]
  Where:
  • [primary_server] is the ingest location of the server
  • [host_port] is the port (by default 1935 )
  • [application] is the application name for the stream assigned by Wowza Video
• Stream key is the stream_name value, such as b01bda67 .
• Username and Password are the username and password values.

Other encoders might use different names in their user interface, like Address instead of URL and Stream instead of Stream key. Make sure to refer to your encoder's documentation to determine the correct locations.

3. Test the connection

Now that you have configured your source, you can test your live stream. You'll need the [live_stream_id] returned in step 1. For a pull stream, ensure that your camera and source encoder are streaming when you start the transcoder so that the stream can be pulled into Wowza Video.

1. Start your live stream.

   Endpoint Reference

   Copy

   Copied

   curl -X PUT \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/live_streams/[live_stream_id]/start"

2. Check the state to make sure the live stream started.

   Endpoint Reference

   Copy

   Copied

   curl -X GET \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/live_streams/[live_stream_id]/state"

3. Start the stream in the RTMP encoder. How you start the encoder varies by device.
4. Fetch a URL to a thumbnail that you can enter into a browser and visually confirm the stream is playing.

   Endpoint Reference

   Copy

   Copied

   curl -X GET \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/live_streams/[live_stream_id]/thumbnail_url"

5. Stop the live stream.

   Endpoint Reference

   Copy

   Copied

   curl -X PUT \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/live_streams/[live_stream_id]/stop"

6. Stop the stream in the source camera or encoder.

Related Topics

To increase security on the playback side, see these articles:

• Manage HLS playback over SSL with the Wowza Video REST API
• Geo-block stream targets with the Wowza Video REST API

Transcoder workflow

1. Create a transcoder

In the transcoder workflow, you'll manually configure the transcoder, output renditions, and stream targets to fit your specific streaming solution. A push stream indicates that your video source will push the stream to Wowza Video.

Create a transcoder that receives a source by sending a POST request to the /transcoders endpoint.

You can use the following sample request, making sure to:

• Set protocol to the protocol you are using.
• Set broadcast_location to the region that's closest to your video source.
• Set delivery_method to push .
• Consider configuring your own username and password values for authentication. User authentication is required by default for transcoders. The username and password are case-sensitive and can only contain alphanumeric, period (.), underscore ( _ ), and hyphen (-) characters. If you don't include them in your request to create the live stream, Wowza Video will assign username and password values for you and return them in the response.
• Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{    
  "transcoder": { 
    "billing_mode": "pay_as_you_go",      
    "broadcast_location": "us_west_oregon",      
    "delivery_method": "push",      
    "name": "My user authenticated push transcoder",      
    "protocol": "rtmp",      
    "transcoder_type": "transcoded", 
    "username": "user123", 
    "password": "abcPassword" 
  } 
}' 

"${WV_HOST}/api/${WV_VERSION}/transcoders" 

Sample response

The response includes:

• An ID for the transcoder that you'll use throughout the rest of this task.
• An empty outputs array that you'll configure in step 2.
• source_connection_information you'll use in step 3 to configure an RTMP source for the stream.
  • domain_name , source_port , application_name , stream_name , username , and password .

{ 
  "transcoder": { 
    "id": "tmd8ybp2", 
    "name": "My user authenticated push transcoder", 
    "transcoder_type": "transcoded", 
    "billing_mode": "pay_as_you_go", 
    "broadcast_location": "us_west_california", 
    ... 
    "protocol": "rtmp", 
    "delivery_method": "push", 
    "source_port": 1935, 
    "domain_name": "[wowzasubdomain].entrypoint.cloud.wowza.com", 
    "application_name": "app-ca51", 
    "stream_name": "b40618d9", 
    ...
    "disable_authentication": false, 
    "username": "user123", 
    "password": "abcPassword", 
    "watermark": false, 
    "created_at": "2018-08-03T19:34:26.000Z", 
    "updated_at": "2018-08-03T19:34:26.000Z", 
    "direct_playback_urls": { 
      "rtmp": ["name and url returned here"], 
      "rtsp": ["name and url returned here"], 
      "wowz": ["name and url returned here"] 
    }, 
    "outputs": []
  } 
} 

2. Add output renditions and stream targets

Complete the transcoder by adding output renditions and stream targets. For instructions, see one of the following articles, depending on whether you're creating an adaptive bitrate or passthrough transcoder:

• Adaptive bitrate transcoder — Create an ABR stream and send it to a target with the Wowza Video REST API
• Passthrough transcoder — Pass a stream through the transcoder to a target with the Wowza Video REST API

3. Configure your video source

Use the source_connection_information from the live stream response to configure your RTMP encoder. You'll need to refer to documentation for your specific encoder to determine where to input the source_connection_information settings, which include the stream and user credentials for authentication.

If you were configuring OBS as the encoder, you'd enter the following stream settings in OBS:

• URL is formatted as:
  rtmp:// [ primary_server ] : [ host_port ] / [ application ]
  Where:
  • [primary_server] is the ingest location of the server
  • [host_port] is the port (by default 1935 )
  • [application] is the application name for the stream assigned by Wowza Video
• Stream key is the stream_name value, such as b01bda67 .
• Username and Password are the username and password values.

Other encoders might use different names in their user interface, like Address instead of URL and Stream instead of Stream key. Make sure to refer to your encoder's documentation to determine the correct locations.

4. Test the connection

Now that you have configured your source, you can test your transcoder. You'll need the [transcoder_id] returned in step 1. For a pull stream, ensure that your camera and source encoder are streaming when you start the transcoder so that the stream can be pulled into Wowza Video.

1. Start the transcoder.

   Endpoint Reference

   Copy

   Copied

   curl -X PUT \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/start"

2. Check the state to make sure the transcoder started.

   Endpoint Reference

   Copy

   Copied

   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/state"

3. Start the stream in the RTMP encoder. How you start the encoder varies by device.
4. Fetch a URL to a thumbnail that you can enter into a browser and visually confirm the stream is playing.

   Endpoint Reference

   Copy

   Copied

   curl -X GET \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/thumbnail_url"

5. Stop the transcoder.

   Endpoint Reference

   Copy

   Copied

   curl -X PUT \
   -H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/stop"

6. Stop the stream in the source camera or encoder.

Related Topics

To increase security on the playback side, see these articles:

• Manage HLS playback over SSL with the Wowza Video REST API
• Geo-block stream targets with the Wowza Video REST API
• Protect streams with token authorization with the Wowza Video REST API