Authentication

The JW Platform Management API 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.

Authentication parameters

In order to authenticate an API call the following parameters are required:

api_key

API key identifies the user to the API. It can be found in the JW Platform dashboard under the account tab.

API shared secret

A secret shared between the API and the user. It is used to create the API signature. Shared secret MUST be never 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_timestamp

API timestamp is the current UNIX timestamp (32 bits signed integer). It is used to protect against replay-attacks.

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.

Warning

All four API authentication parameters (api_key, api_timestamp, api_nonce and generated api_signature) MUST be always present in the API call.

API signature generation

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:

1: All text parameters converted to UTF-8 encoding.

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

2: All text parameters URL-encoded (see OAuth Core 1.0 Section 5.1).

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

3: Parameters are sorted based on their encoded names (see OAuth Core 1.0 Section 9.1.1). Sort order is lexicographical byte value ordering.

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

4: Parameters are concatenated together into a single string. Each parameter’s name is separated from the corresponding value by an ‘=’ character (even if the value is empty), and 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

5: The secret is added and SHA-1 digest is calculated. Secret is added to the end of the SBS:

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

6: The calculated SHA-1 HEX digest for the above string 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

Protection against replay-attacks

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