Authentication
If you are using the Platform Management API v2, please read this Authentication article.
Platform Management API v1
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.
Authentication parameters
In order to authenticate an API call the following parameters are required:
| Parameter | Description |
|---|---|
| API shared secret | A secret shared between the API and the user. It is used to create the API signature. Shared secret MUST never be included in the API call or shared with somebody else except JW Platform account owners. It can be found in the JW Platform Dashboard under the account tab. |
api_key | API key identifies the user to the API. It can be found in the JW Platform dashboard under the account tab. |
api_nonce | API nonce is an 8 digits random number. It is used to make sure that API signature is always unique, even if the same call has been made twice within one second. |
api_signature | SHA-1 digest of the api_key, api_timestamp, api_nonce and other call parameters. |
api_timestamp | API timestamp is the current UNIX timestamp (32 bits signed integer). It is used to protect against replay-attacks. |
WARNING
All four API authentication parameters (
api_key,api_timestamp,api_nonceand generatedapi_signature) must be always present in the API call.
Generate an API signature
The API signature is a SHA-1 digest and it is generated similar to how it is specified in OAuth Core 1.0 protocol. First, Signature Base String (SBS) is constructed:
- Convert all text parameters into UTF-8 encoding.
text démo
api_format xml
api_key XOqEAfxj
api_nonce 80684843
api_timestamp 1237387851
- URL encode all text parameters. See: OAuth Core 1.0 Section 5.1.
text d%C3%A9mo
api_format xml
api_key XOqEAfxj
api_nonce 80684843
api_timestamp 1237387851
- 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
text d%C3%A9mo
- Concatenate the parameters together 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&text=d%C3%A9mo
- Add the secret to the end of the SBS.
api_format=xml&api_key=XOqEAfxj&api_nonce=80684843&api_timestamp=1237387851&text=d%C3%A9mouA96CFtJa138E2T5GhKfngml
- Calculate the SHA-1 HEX digest for the single string. For example, the calculated SHA-1 HEX digest for the sting the previous step will be:
fbdee51a45980f9876834dc5ee1ec5e93f67cb89
An authenticated API call will look like this:
http://api.jwplatform.com/v1/videos/list?text=d%C3%A9mo&api_nonce=80684843&
api_timestamp=1237387851&api_format=xml&
api_signature=fbdee51a45980f9876834dc5ee1ec5e93f67cb89&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_timestampandapi_noncemake 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 3 months ago