Manage your library with the Management API v1

🚧

We strongly recommend using the v2 Management API to manage your library. It is more secure and more performant, plus newer capabilities will only be made available in v2.

Learn more about the v2 Management API benefits and migration steps.

The Platform Management API enables you to manage all aspects of your library. If you need to create a player for a specific use case, upload content programmatically, or manage the security of your content, you can use the Platform Management API to complete these tasks.

In 2021, JW Player released Platform Management API v2 (v2). In addition to the capabilities of Platform Management API v1 (v1), v2 includes the following improvements:

• API key management
• Granular access control
• RESTful API design practices
• Ease of use

Authentication

The Platform Management API v1 uses signature-based authentication to verify the identity of an API user. In order to make API calls, a user needs his API Key and API Secret, which can both be found in the account tab of the Dashboard.

Required Values

The following table lists the values required to authenticate an API call.

Generate an API signature

The API signature is a SHA-1 digest that is generated similar to the specifications in the OAuth Core 1.0 protocol.

Use the following steps to generate the API signature:

1. Convert the api_key, api_nonce, api_timestamp, and all other query parameters into UTF-8 encoding.
   
   In addition to the authentication parameters, the following list includes the format of the API response (api_format) and a query parameter (search).

api_key         XOqEAfxj
api_nonce       80684843
api_timestamp   1237387851
api_format      xml
search          démo

2. URL-encode all the values from the previous step. See: OAuth Core 1.0 Section 5.1.

api_key         XOqEAfxj
api_nonce       80684843
api_timestamp   1237387851
api_format      xml
search          d%C3%A9mo

3. Sort the parameters based on their encoded names. Sort order is lexicographical byte value ordering. See: OAuth Core 1.0 Section 9.1.1.

api_format      xml
api_key         XOqEAfxj
api_nonce       80684843
api_timestamp   1237387851
search          d%C3%A9mo

4. Concatenate the parameters into a single string. Each parameter’s name is separated from the corresponding value by an = character (even if the value is empty). Each name-value pair is separated by an & character. See: OAuth Core 1.0 Section 9.1.1.

api_format=xml&api_key=XOqEAfxj&api_nonce=80684843&api_timestamp=1237387851&search=d%C3%A9mo

5. Add the secret to the end of the Signature Base String (SBS).

api_format=xml&api_key=XOqEAfxj&api_nonce=80684843&api_timestamp=1237387851&search=d%C3%A9mouA96CFtJa138E2T5GhKfngml

6. Calculate the SHA-1 HEX digest for the single string. For example, the calculated SHA-1 HEX digest for the string the previous step will be: 600822503e043c017e01ce5c9796f83e7ee169f5.
   
   An authenticated API call will look like this:

http://api.jwplatform.com/v1/videos/list?search=d%C3%A9mo&api_nonce=80684843&
   api_timestamp=1237387851&api_format=xml&
   api_signature=600822503e043c017e01ce5c9796f83e7ee169f5&api_key=XOqEAfxj

Protect against replay attacks

When the signature-based method is used it is possible that the call can be captured by a malicious party and “replayed” later. To protect against this type of attacks, the JW Platform Management API implemented the following measures:

• api_timestamp and api_nonce make sure that the API call signature is always unique.
• API calls with timestamps that are over 27 hours old will be denied.
• The API keeps a history of all call signatures for the last 48 hours. If a certain signature already exists in the history, the API call will be not executed.

Output Formats

The JW Platform Management API can deliver the data returned with API calls in various formats. You can freely choose the format that best fits your needs. Because of its nature of nodes and attributes, the XML format slightly differs from the other output formats.

Formats

The following formats are supported:

• py: Serialized Python (using the highest data stream protocol version (HIGHEST_PROTOCOL) of the pickle module)
• json: JSON (JavaScript Object Notation)
• xml: XML
• php: Serialized PHP

🚧

The output format is specified using the api_format parameter. It must be provided with each API call.

Interoperability

The structure of the XML output format differs from the other formats, since XML allows for the use of attributes in its data structure (this is also recommended). Totals, keys, and IDs are, for example, placed as attributes in XML. To illustrate, here’s a possible return from the /videos/list call in XML format:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <videos total="22">
    <video key="yYul4DRz">
      <author>JW Platform</author>
      <date>1225962900</date>
      <description>New video</description>
      <duration>12.0</duration>
      <link>http://www.jwplatform.com</link>
      <status>ready</status>
      <tags>new, video</tags>
      <title>New test video</title>
    </video>
    ...
  </videos>
</response>

Here is the same return in PHP format. As you can see, the key attribute is a parameter and the total attribute is not returned as PHP count() function can be used to get total number of videos.

[status] => ok
[videos] => Array (
    [0] => Array (
        [status] => ready
        [description] => New video.
        [tags] => new, video
        [title] => New test video
        [duration] => 12.0
        [link] => http://www.jwplatform.com
        [author] => JW Platform
        [key] => yYul4DRz
        [date] => 1225962900
    ...
    )
)

Error Handling

Whenever the API is unable to process a call, it will return an error. This happens e.g. when required parameters are missing, when authentication fails or when parameters are out of bounds.

Error Messages

If an API call succeeds, it always returns data in the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  ...
</response>

If an API call fails, an error message is returned. Errors are always structured as follows:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>error</status>
  <code>ParameterInvalid</code>
  <title>Invalid Parameter</title>
  <message>video_key: Video with the key aT2u4xRa does not exist</message>
</response>

The error message has the following parameters:

In addition to returning an error message, the API sets the HTTP Status Code of the call response to the error specific code, instead of the regular status 200 OK.

Error Codes

Here is a full list of error codes that can be returned if an API call fails:

📘

Sending strings that contain colons (for example, in URLs) will cause SignatureInvalid errors. Please refer to API signature generation documentation.