General Algorithm for Signing Requests

Every request made to Backlot requires three query string parameters for authentication: API key, request expiration, and signature. This topic tells how to generate the signature.

To sign a request:

  1. Start with your 40-character secret key. Find it in the Developers tab in the Backlot UI). The secret key is unique for each user and should always be kept secure and private. For details, see Your API Credentials. This example uses the following fictitious secret key:
    329b5b204d0f11xxxxxxxxxxxxxxxxxxxx18xqh5
        
  2. Append the HTTP method (e.g. "GET", "POST", or "PUT"):
         329b5b204d0f11xxxxxxxxxxxxxxxxxxxx18xqh5GET
        
  3. Append the request path or route:
     
          329b5b204d0f11xxxxxxxxxxxxxxxxxxxx18xqh5GET/v2/players/HbxJK      
         
  4. Append any query string parameters, sorted alphabetically. This includes the required API key, found in the Developers tab in the Backlot UI, and the expires parameter. Omit the parameter prefix characters, such as & or ?. This example uses the following fictitious API key:
         7xxxX
        

    Note: Do not URL-encode these parameters. This is done in a later step.

          329b5b204d0f11xxxxxxxxxxxxxxxxxxxx18xqh5GET/v2/players/HbxJKapi_key=7xxxXexpires=1299991855
        
  5. If your request has a body, append the entire request body to the string.
  6. From this string, generate a SHA-256 digest in base64. You might use bash or node.js for this. The encoding need not necessarily be unique. In bash, you might use the following piped commands:
    echo -n "329b5b204d0f11xxxxxxxxxxxxxxxxxxxx18xqh5GET/v2/players/HbxJKapi_key=7xxxXexpires=1299991855" | shasum -a 256 | awk '{print $1}' | xxd -r -p | base64
    (This command works for Mac OS X. If you are using another version of Linux, you might prefer to use sha256sum instead of shasum -a 256.)

    The output is a string like the following example:

    ZWU3NGYzM2RkZDMxZTJmMjgxOTY0OThhOWM3YjcyOTg4OTA5OTYzNzIxN2FmN2YxYzVjYWQ2YjVjZDIyYjY4ZSAgLQo=
  7. Truncate the string to 43 characters and remove any trailing = signs. For example:
    ZWU3NGYzM2RkZDMxZTJmMjgxOTY0OThhOWM3YjcyOTg
        
  8. Now URL-encode the signature. For example, / becomes %2F and + becomes %2B. In this example, the string remains the same:
    ZWU3NGYzM2RkZDMxZTJmMjgxOTY0OThhOWM3YjcyOTg
        
  9. Append this signature to your request URL as a query string parameter. If you use query string parameters with non-ASCII letters or ' characters, make sure they are escaped. You can now visit this URL to make your request. The following example is the final signed URL:
    https://api.ooyala.com/v2/players/HbxJKM?api_key=7xxxX&expires=1299991855&signature=ZWU3NGYzM2RkZDMxZTJmMjgxOTY0OThhOWM3YjcyOTg
        

Was this article helpful?