Authentication

👍

If you are using the Platform Management API v2, please read this Authentication article.


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.

📘

TIP

If you are not a developer or prefer a simpler implementation, you can use one of JW Player's client libraries.



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.


Did this page help you?