Manage your library with the Management API v1


📘

As of October 2021, the Platform Management API v2 was generally available to all customers. We strongly recommend using the v2 API to manage your library and content as the v1 API will be deprecated in June 2023.


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.

ValueDescription
SecretShared site API credential

1. From your API Credentials page, scroll down to the v1 API Credentials section.
2. Click Show Credentials in the row of the relevant PROPERTY NAME.
3. Copy the Secret.

This shared secret must never be included in the API call or shared with somebody else except with other account owners.
api_key stringUnique identifier of the property

1. From your API Credentials page, scroll down to the v1 API Credentials section.
2. Click Show Credentials in the row of the relevant PROPERTY NAME.
3. Copy the Key.
api_nonce integerEight-digit random number

The nonce ensures that the API signature is always unique.
api_signature stringSHA-1 digest of the api_key, api_timestamp, api_nonce and other call parameters
api_timestamp integerCurrent UNIX timestamp (32-bit signed integer)

The timestamp protects against replay attacks.


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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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:

ParametersStringDescription
statusStringCall execution status. Set to error if call has failed.
codeStringAn error code.
titleStringError title (short error description).
messageStringDetailed error description.

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:

ErrorDescription
UnknownError- title: An Unknown Error occurred

- HTTP Status: 400 Bad Request
InternalError- title: Internal Error

- HTTP Status: 500 Internal Server Error
NotFound- title: Not Found

- HTTP Status: 404 Not Found
NoMethod- title: No Method Specified

- HTTP Status: 400 Bad Request
NotImplemented- title: Method Not Implemented

- HTTP Status: 501 Not Implemented
NotSupported- title: Method or parameter not supported

- HTTP Status: 405 Method Not Allowed
CallInvalid- title: Call Invalid

- HTTP Status: 400 Bad Request
DatabaseError- title: Database Error

- HTTP Status: 500 Internal Server Error
FileUploadFailed- title: File Upload Failed

- HTTP Status: 400 Bad Request
ItemAlreadyExists- title: Item Already Exists

- HTTP Status: 409 Conflict
PermissionDenied- title: Permission Denied

- HTTP Status: 403 Forbidden
PreconditionFailed- title: Method Precondition Failed

- HTTP Status: 412 Precondition Failed
ParameterMissing- title: Missing Parameter

- HTTP Status: 400 Bad Request
ParameterInvalid- title: Invalid Parameter

- HTTP Status: 400 Bad Request
ParameterEmpty- title: Empty Parameter

- HTTP Status: 400 Bad Request
APIParameterEncodingError- title: Parameter Encoding Error

- HTTP Status: 400 Bad Request
ParameterTypeEmpty- title: Parameter Type Error

- HTTP Status: 400 Bad Request
ApiKeyMissing- title: User Key Missing

- HTTP Status: 400 Bad Request
ApiKeyInvalid- title: User Key Invalid

- HTTP Status: 400 Bad Request
DigestInvalid- title: Digest Invalid

- HTTP Status: 400 Bad Request
FileSizeInvalid- title: File Size Invalid

- HTTP Status: 400 Bad Request
TimestampMissing- title: Timestamp Missing

- HTTP Status: 400 Bad Request
TimestampInvalid- title: Timestamp Invalid

- HTTP Status: 400 Bad Request
TimestampExpired- title: Timestamp Expired

- HTTP Status: 403 Forbidden
NonceMissing- title: Nonce Missing

- HTTP Status: 400 Bad Request
NonceInvalid- title: Nonce Invalid

- HTTP Status: 400 Bad Request
SignatureMissing- title: Signature Missing

- HTTP Status: 400 Bad Request
SignatureInvalid- title: Signature Invalid

- HTTP Status: 400 Bad Request

📘

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