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.
Value | Description |
---|---|
Secret | Shared 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 string | Unique 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 integer | Eight-digit random number The nonce ensures that the API signature is always unique. |
api_signature string | SHA-1 digest of the api_key , api_timestamp , api_nonce and other call parameters |
api_timestamp integer | Current 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:
- 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
- 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
- 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
- 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
- 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
- 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
andapi_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.
Updated 5 months ago