Authentication¶
The Bits on the Run 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 Bits on the Run 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 Bits on the Run account owners. It can be found in the Bits on the Run 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.bitsontherun.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 Bits on the Run 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.