Skip to main contentIBM Video Streaming Developers

Embed restriction

All IBM Video Streaming channels can be embedded anywhere across the internet by default. By restricting the embed URLs, you can control the viewing experience and limit distribution to your own preferred partners.

Get embed lock status

This request returns the embed lock status.

GET https://api.video.ibm.com/channels/{channel_id}/locks/embed.json

Parameters

This request has no parameters.

Success response

Upon success, a key-value structure is returned.

KEYTYPEDESCRIPTION
lockedstringReturns TRUE if the embed lock is enabled on the channel, otherwise FALSE.

Example of a success response:

{
"locked": "TRUE"
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
404 Not Foundnot_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Modify embed lock

Enable or disable embed restrictions on a channel. When embed lock is enabled (locked == TRUE), embedding the content of this channel is allowed only on whitelisted URLs.

PUT https://api.video.ibm.com/channels/{channel_id}/locks/embed.json

Parameters

The parameters for the PUT request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
lockedstringREQUIREDSet embed lock on channel when this value is TRUE. Removes embed lock when the value is FALSE.

Success response

Upon success a response with HTTP status “204 No Content” is returned.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad Requestinvalid_requestThe request parameter is missing or invalid
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Get embed lock URL whitelist

This request returns the list of whitelisted URLs.

GET https://api.video.ibm.com/channels/{channel_id}/locks/embed/allowed-urls.json

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned with the following key-value structures.

KEYTYPEDESCRIPTION
allowed_urlsarrayURL list from the allowed URLs embed lock list no matter where it was set. Empty array if locked == “FALSE”.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Add URL to the embed lock URL whitelist

Add a specific URL to the whitelist that controls where embedding of channel content is allowed when embed lock is enabled.

POST
https://api.video.ibm.com/channels/{channel_id}/locks/embed/allowed-urls.json

Parameters

The parameters for the POST request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
urlstringREQUIREDThe URL to be added to the whitelist

You can add one URL per API call.

Success response

Upon success a response with HTTP status “201 Created” is returned.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad Requestinvalid_requestThe request parameter is missing or invalid
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Empty the embed lock URL whitelist

Remove all URLs from the embed lock whitelist.

DELETE https://api.video.ibm.com/channels/{channel_id}/locks/embed/allowed-urls.json

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request