# Manage user authentication for HLS streams with the Wowza Video REST API When you broadcast an HLS stream using the Wowza Video™ service, you have control over whether or not the source encoder must use user authentication in order to publish an RTMP or RSTP stream. User authentication provides a secure connection from the source encoder into the ingest origin server for Wowza Video and prevents third parties from connecting to and altering your stream. This article shows how to use the Wowza Video REST API to create a live stream or transcoder with user authentication for RTMP and RTSP streams that are delivered to Wowza Video with a push or pull connection. It also provides information on configuring a source encoder so that it can be authenticated for connection, and it points to information on securing HLS streams during playback. ## Before you start You should be familiar with the following concepts: - **API authentication** **methods**. We use JSON web tokens for API authentication. See [Authentication](/docs/wowza-video/about-the-rest-api/authentication) for more information. - **Environment variables**. We use environment variables for the API version and your JWT in the cURL API request examples in this topic to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. If you don't set environment variables for these values, you'll need to manually enter the correct values in the code samples throughout this tutorial. See [Tools for testing the API](/docs/wowza-video/about-the-rest-api/api-overview#tools-for-testing-the-api) for instructions. You should complete the following tasks: - **Install the latest firmware** for your encoder. You should have access to the following items: - The **encoder's user guide** for details about how to operate the device or software and how to specify settings such as resolution, bitrate, and frame rate. You should choose between the following two workflows: - Decide between the **live stream** or **transcoder** workflow. See Decide between a live stream or transcoder workflow for more information about these workflows. details summary Live stream workflow ## 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. Info This topic uses the push delivery method. If you use the pull delivery method, configure the source by determining and providing the `source_url` value when creating the live stream. The `source_url` must be an RTMP URL with a publicly accessible hostname or IP address. ### 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 ``` 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 ``` 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 ``` 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 ``` 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](/docs/wowza-video/guides/stream-security/manage-hls-playback-over-ssl-for-wowza-cdn-on-fastly) - [Geo-block stream targets with the Wowza Video REST API](/docs/wowza-video/guides/stream-security/geoblock-wowza-cdn-on-fastly-stream-targets) details summary Transcoder workflow ## 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: Info You'll need the transcoder ID from step 1. - **Adaptive bitrate transcoder** — [Create an ABR stream and send it to a target with the Wowza Video REST API](/docs/wowza-video/guides/more-tasks/create-an-abr-stream-and-send-to-a-target) - **Passthrough transcoder** — [Pass a stream through the transcoder to a target with the Wowza Video REST API](/docs/wowza-video/guides/more-tasks/pass-a-stream-through-the-transcoder-to-a-target) ### 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. Info This topic uses the push delivery method. If you use the pull delivery method, configure the source by determining and providing the `source_url` value when creating the live stream. The `source_url` must be an RTMP URL with a publicly accessible hostname or IP address. ### 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 ``` 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 ``` -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 ``` curl -X GET \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/thumbnail_url" ``` 5. Stop the transcoder. Endpoint Reference ``` 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](/docs/wowza-video/guides/stream-security/manage-hls-playback-over-ssl-for-wowza-cdn-on-fastly) - [Geo-block stream targets with the Wowza Video REST API](/docs/wowza-video/guides/stream-security/geoblock-wowza-cdn-on-fastly-stream-targets) - [Protect streams with token authorization with the Wowza Video REST API](/docs/wowza-video/guides/stream-security/protect-wowza-cdn-on-fastly-stream-target-with-token-authentication)