Authentication

Transloadit uses a very simple authentication system based on JSON and HMAC signatures. By default authentication is disabled and you need to enable it.

Enabling authentication

To require requests against your account to be signed, do the following:

• Go to the API Credentials page under "My Account" -> "Account settings"
• Check the "Enable Authentication" checkbox
• Hit the update button

Using authentication

Your typical Transloadit template or assembly request params field usually contains:

{
    auth: { key: '23c96d084c744219a2ce156772ec3211' },
    steps: {...}
}

Where auth.key is the "Auth Key" you find on your API Credentials page.

In order to sign this request, you have to add an additional field auth.expires. This field must contain a timestamp in the (near) future, after which the signature will no longer be accepted. Use "YYYY/MM/DD HH:II:SS+00:00" as the date format, and make sure the used timezone is UTC, for example:

{
    auth:{
        "expires":"2009/11/27 16:53:14+00:00",
        "key":"2b0c45611f6440dfb64611e872ec3211"
    },
    steps: {...}
}

To calculate the signature for this request.

1. Encode the above JS object into a JSON string.
2. Calculate an RFC 2104-compliant HMAC hex signature with the string you just created, your auth secret as the key using SHA1 as the hash algorithm.
3. Add a new (hidden) field to your form / post request called signature, and fill it with the signature value created in step 2.

Raw example

When testing your signature method against the following params:

{
    "auth": {
        "expires":"2010/10/19 09:01:20+00:00",
        "key":"2b0c45611f6440dfb64611e872ec3211"
    },
    "steps": {
        "encode": {
          "robot": "/video/encode"
        }
    }
}

You should use the following (or similar / valid) JSON message to sign:

{"auth":{"expires":"2010\/10\/19 09:01:20+00:00","key":"2b0c45611f6440dfb64611e872ec3211"},"steps":{"encode":{"robot":"\/video\/encode"}}}

Given an auth secret of d805593620e689465d7da6b8caf2ac7384fdb7e9, this would yield the following signature:

fec703ccbe36b942c90d17f64b71268ed4f5f512

Your final request would look like this:

params=%7B%22auth%22%3A%7B%22expires%22%3A%222009%2F11%2F27%2016%3A53%3A14%2B00%3A00%22%2C%22key%22%3A%222b0c45611f6440dfb64611e872ec3211%22%7D%7D&signature=4e14c4b0a16d01991c0f7276d68e03ded49cc212

Implementations

Ruby

require 'rubygems'
require 'openssl'
require 'json'

auth_key = 'YOUR-AUTH-KEY'
auth_secret = 'YOUR-AUTH-SECRET'

params = JSON.generate({:auth => {
  :expires => Time.now.utc.strftime('%Y/%m/%d %H:%M:%S+00:00'),
  :key => auth_key,
}})
digest = OpenSSL::Digest::Digest.new('sha1')
signature = OpenSSL::HMAC.hexdigest(digest, auth_secret, params)

PHP

$authKey = 'YOUR-AUTH-KEY';
$authSecret = 'YOUR-AUTH-SECRET';

$params = json_encode(array(
  'auth' => array(
    'expires' => gmdate('Y/m/d H:i:s+00:00', strtotime('+1 hour')),
    'key' => $authKey,
  )
));
$signature = hash_hmac('sha1', $params, $authSecret);

More authentication options

Here are some additional keys you can include in your auth parameter to restrict uploads:

Key	Description
referer	A regular expression to match against the http referer of this upload. Uploads without a referer will always pass (some people have them disabled). You can use this to make sure people only upload from your domain. Sample value: "example\\.org". See Mozilla's RegExp docs for more information.
max_size	The maximum size an upload can have in bytes. This is useful if you don't want your users to upload 2GB files. Example: 1048576 (1 MB). You need to use max_size in the hidden params field of your form. Setting max_size in your template will have no effect at the moment.

Comments