SAPI Authentication

The Blue Billywig “Server API” (SAPI) requires authentication using time-based one-time passwords (TOTP).

1.0 | Calculate a token

• Create an API key (learn more about creating and managing API keys).
• In the API key details:
  • Copy the shared secret. It is displayed in the format {id}-{hex_secret}, for example 490-55c491d354cfefb9b4d26cf22fbdd0a1. The number before the dash is the key ID; the hex string after the dash is the shared secret.
    >
    
    >
    
    Prevent access to your credentials

    API keys offer access to your data. Make sure you don’t expose your API credentials in public repositories or client-side code.

• Apply a token expiration / TTL (“time to live”) of 120 seconds.

2.0 | Authenticate an API call

In the header of your API call, pass rpctoken containing both the API key ID and a 10-digit calculated token:

{API_KEY_ID}-{CALCULATED_TOKEN}

For example:

490-9784651320

Alternatively, pass rpctoken as a query parameter on the URL. For example:

https://yourcompany.bbvms.com/sapi/mediaclip/1234567?rpctoken=490-9784651320

3.0 | Code Examples

3.1 | Node.js

The following example uses the otplib package to calculate a 10-digit time-based token with an expiration of 120 seconds. The calculated token should then be concatenated with the API key ID and passed in the header as rpctoken in your API call.

The node-fetch package is used to make the API call.

Install otplib and node-fetch:

npm i otplib
npm i node-fetch

Example code to request the clip data of clip 1234567:

3.2 | PHP

The following example uses a PHP class for HMAC-based one-time passwords (hotp-php) to calculate a 10-digit time-based token with an expiration of 120 seconds.

Concatenate the calculated token with the API key ID and pass it in the header as rpctoken in your API call.

<?php
include_once("/PATH/TO/hotp.class.php");

$apiKeyId = '490';                                  // number before the dash
$sharedSecret = '55c491d354cfefb9b4d26cf22fbdd0a1'; // hex string after the dash

$expire = 120;
$result = HOTP::generateByTime($sharedSecret, $expire, time());
$output = $apiKeyId . '-' . $result->toString();
echo $output;
?>