warning icon

Deprecation Warning: This API is deprecated and it is scheduled to be removed on 03/01/2022. Please use (or migrate to) the new version of the Viewer Authentication.

Channel level

PUT https://api.video.ibm.com/channels/CHANNEL_ID/locks/hash/advanced.json
Copy to clipboard

Parameters

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`url`	string	REQUIRED	URL of the authentication flow entry point
`secret`	string	REQUIRED	Secret key

Response

HTTP response codes returned when the action is successful:

HTTP RESPONSE CODE	DESCRIPTION
201 Created	Viewer authentication has been set up on the channel with the new hash.
204 No Content	Viewer 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 VALUE	HTTP RESPONSE	CODE DESCRIPTION
`invalid_request`	400 Bad Request	One or more required parameters are missing (secret, url).
`invalid_type`	400 Bad Request	The URL is invalid.
`lack_of_ownership`	403 Forbidden	The api user is not allowed to manage the given channel
`not_found`	404 Not found	Channel 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
Copy to clipboard

Parameters

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`url`	string	REQUIRED	URL of the authentication flow entry point
`secret`	string	REQUIRED	Secret key

Response

HTTP response code returned when the action is successful:

HTTP RESPONSE CODE	DESCRIPTION
204 No content	Viewer 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
Copy to clipboard

The order of the parameters should match their order in the array when creating the hash.

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
Copy to clipboard

Managing viewer authentication settings

Getting channel viewer authentication settings

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

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"
  }
Copy to clipboard

Specific error codes returned when the action failed:

ERROR VALUE	HTTP RESPONSE CODE	DESCRIPTION
`lack_of_ownership`	403 Forbidden	The API user is not allowed to manage the given channel
`not_found`	404 Not found	Channel not found

Removing channel viewer authentication

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

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 VALUE	HTTP RESPONSE CODE	DESCRIPTION
`lack_of_ownership`	403 Forbidden	The api user is not allowed to manage the given channel
`not_found`	404 Not found	Channel not found

Getting video viewer authentication settings

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

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"
  }
}
Copy to clipboard

Specific error codes returned when the action failed:

ERROR VALUE	HTTP RESPONSE CODE	DESCRIPTION
`lack_of_ownership`	403 Forbidden	The api user is not allowed to manage the given channel
`not_found`	404 Not found	Video 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
Copy to clipboard

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 VALUE	HTTP RESPONSE CODE	DESCRIPTION
`lack_of_ownership`	403 Forbidden	The api user is not allowed to manage the given channel
`not_found`	404 Not found	Video or specific authentication settings not foun

Edit this page on GitHub

Deprecated: Getting started

Deprecated: Hash lifetime and expiration

Deprecated - Implementing viewer authentication

Channel level

Video level

Set up viewer authentication for a video

Implementing the authentication response

Managing viewer authentication settings

Getting channel viewer authentication settings

Parameters

Response

Removing channel viewer authentication

Parameters

Response

Getting video viewer authentication settings

Parameters

Response

Removing specific video viewer authentication settings

Parameters

Response