Skip to main contentIBM Video Streaming Developers

Implementing viewer authentication

Channel level

PUT https://api.video.ibm.com/channels/CHANNEL_ID/locks/hash/advanced.json
Parameters
PARAMETERTYPEIMPORTANCEDESCRIPTION
urlstringREQUIREDURL of the authentication flow entry point
secretstringREQUIREDSecret key
Response

HTTP response codes returned when the action is successful:

HTTP RESPONSE CODEDESCRIPTION
201 CreatedViewer authentication has been set up on the channel with the new hash.
204 No ContentViewer authentication has been set up on the channel by updating the existing hash with the new one.

Specific error codes returned when the action failed:

ERROR VALUEHTTP RESPONSECODE DESCRIPTION
invalid_request400 Bad RequestOne or more required parameters are missing (secret, url).
invalid_type400 Bad RequestThe URL is invalid.
lack_of_ownership403 ForbiddenThe api user is not allowed to manage the given channel
not_found404 Not foundChannel not found

Video level

By default videos inherit the authentication settings from channels but it can be overridden on a video by video basis.

Set up viewer authentication for a video

PUT https://api.video.ibm.com/videos/VIDEO_ID/locks/hash.json
Parameters
PARAMETERTYPEIMPORTANCEDESCRIPTION
urlstringREQUIREDURL of the authentication flow entry point
secretstringREQUIREDSecret key
Response

HTTP response code returned when the action is successful:

HTTP RESPONSE CODEDESCRIPTION
204 No contentViewer authentication has been set up on the video

Implementing the authentication response

If the authentication was successful, your service must pass an authentication response to the player. The authentication response must be a JSON encoded array which contains the following:

  • list of parameters that have been hashed
  • the MD5 hash of the string that has been created by concatenating the parameters and the shared secret key with pipe ”|” characters

Example script in PHP for creating the authentication response when the authentication was successful

// We create the array of parameters.
// The parameters can be anything.
$userData = [
"user" => $_SESSION["user"],
"someString" => "someValue"
];
// We create the hash by hashing
// the parameters array contents and

To pass the response to the player your service must redirect the page to the IBM Video Streaming return URL with passing the response in JSON format as a get parameter. You can test the API response at the Hash Authentication Test page.

https://video.ibm.com/embed/hashlock/pass?hash=RESPONSE_IN_JSON_FORMAT

Managing viewer authentication settings

Getting channel viewer authentication settings

GET https://api.video.ibm.com/channels/CHANNEL_ID/locks/hash.json

Parameters

This request has no parameters.

Response

Upon success, key-value pairs are returned under a “hashlock” key.

Example:

{
"hashlock": {
"type": "advanced",
"url": "https://yourdomain.com/auth/123",
"message": null,
"button_caption": null,
"popup_width": "0",
"popup_height": "0"
}

Specific error codes returned when the action failed:

ERROR VALUEHTTP RESPONSE CODEDESCRIPTION
lack_of_ownership403 ForbiddenThe API user is not allowed to manage the given channel
not_found404 Not foundChannel not found

Removing channel viewer authentication

DELETE https://api.video.ibm.com/channels/CHANNEL_ID/locks/hash.json

Parameters

This request has no parameters.

Response

Upon success the 200 OK HTTP response code is returned.

Specific error codes returned when the action failed:

ERROR VALUEHTTP RESPONSE CODEDESCRIPTION
lack_of_ownership403 ForbiddenThe api user is not allowed to manage the given channel
not_found404 Not foundChannel not found

Getting video viewer authentication settings

GET https://api.video.ibm.com/videos/VIDEO_ID/locks/hash.json

Parameters

This request has no parameters.

Response

Upon success, key-value pairs are returned under a “hashlock” key.

Example
{
"hashlock": {
"url": "https://auth.yourdomain.com/video-authentication",
"secret": "TOP_SECRET_KEY"
}
}

Specific error codes returned when the action failed:

ERROR VALUEHTTP RESPONSE CODEDESCRIPTION
lack_of_ownership403 ForbiddenThe api user is not allowed to manage the given channel
not_found404 Not foundVideo or specific authentication settings not found

Removing specific video viewer authentication settings

If you remove specific settings then video will inherit the authentication settings from the channel.

DELETE https://api.video.ibm.com/videos/VIDEO_ID/locks/hash.json

Parameters

This request has no parameters.

Response

Upon success the 204 No Content HTTP response code is returned.

Specific error codes returned when the action failed:

ERROR VALUEHTTP RESPONSE CODEDESCRIPTION
lack_of_ownership403 ForbiddenThe api user is not allowed to manage the given channel
not_found404 Not foundVideo or specific authentication settings not foun