HMAC Signing of API Requests

Description

Typically, our REST APIs require authorization via an OAuth 2.0 bearer token. However, some APIs, like the /files/ API, can also be accessed using HMAC-signed request URLs. HMAC signing is useful for granting third-party access to specific resources or methods without sharing the resource owner's OAuth token, which would provide full and unbounded permissions. HMAC-signed URLs can be one-time or time-limited and only authorize the specific API call signed by the resource owner.

General Steps for using HMAC-based signing of API requests

1. Our APIs are protected by various scopes like mediahub, autograph, me, etc. Only applications with the relevant scopes can access certain APIs. HMAC-based signing follows the same principle, where the signature inherits all scopes of the application used to compute the signature.
2. Create an application with the required scopes. Upon creation, you'll receive a client_id and client_secret.
3. Use the application credentials to HMAC sign the URL and share the presigned URL with users to grant access to specific REST resources.
4. The Xvid API endpoints verify the signature by looking up the corresponding client_secret. Access to the resource is granted only if the signature is successfully verified.

Creating an HMAC signed URL

To create an HMAC-signed URL, you need the client_id and client_secret from your application. The following parameters are associated with HMAC-signed URLs:

• client_id: string
  The Application client_id

• expiry_time: int
  Expiry time, in seconds, after which the signed URL is invalidated. Default is 180 seconds.

• multi_use: boolean (Optional)
  Specifies whether the signed URL can be used multiple times or is invalidated after the first use. Default is True.

Example

Assume the resource owner has created an application with client_id "cb379184054d2011389f5a38" and wants to sign an AutoGraphed file download request:

https://api.xvid.com/v1/files/downloads/?file_id=5463c3882fab72b097d57dee&autograph_tag=ghtcde&redirect=true

For unique autographed downloads, the autograph_tag parameter must be included (otherwise, a HTTP 400 error is returned). The redirect=true parameter ensures the download starts immediately when the user clicks the signed link. This signed link can be used in a hyperlink or HTML5 video tag or sent directly to the end-user.

To prevent modification of query parameters, the entire URL is protected by a cryptographic signature. Append the request URL with parameters (expiry_time, client_id, and multi_use), and sign the entire URL string with HMAC-256 using the client_secret. The calculated signature is appended to the URL as the signature parameter.

Computing a HMAC Signed URL - Python Example

#!/usr/bin/env python

from __future__ import print_function
import time
import base64
import urllib
import hmac
import hashlib

# Client Id and Client Secret of Subscribers Application
client_id = "cb379184054d2011389f5a38"
client_secret = "YOUR_CLIENT_SECRET"

# URL to be signed to provide access to Users
api_base_url = "https://api.xvid.com"
url = "/v1/files/downloads/?file_id=5463c3882fab72b097d57dee&autograph_tag=ghtcde&redirect=true"
validity_in_sec = 30 * 60  # Expiry time of URL (30 minutes)
expires = int(time.time()) + validity_in_sec
multiuse = False

# Append URL parameters
if multiuse:
    url += "&multi_use=true"
url_params = "&client_id=" + urllib.parse.quote_plus(client_id) + "&expiry_time=" + str(expires)
url += url_params

# Sign the URL
key = base64.b64decode(client_secret)
if isinstance(url, str):
    url = url.encode('utf-8')
hashed = hmac.new(key, url, hashlib.sha256)

# Prepare the signed URL by adding the signature at the end
signed_url = api_base_url + url.decode('utf-8') + "&signature=" + hashed.hexdigest()
print(signed_url)