Authentication

Auth Key Authentication

When interfacing with the Transloadit REST API, we require an auth param to be part of the multipart form request. An example of the JSON required for this field is shown below.

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  }
}

The key field refers to the Auth Key associated with your Transloadit Workspace, found on the Credentials page. The above is therefore the minimum to authenticate yourself to use most Transloadit API endpoints, and is required for almost all requests.

Signature Authentication

As part of best practices, we recommend enabling Signature Authentication on your account, especially if you're integrating with Transloadit from an untrusted environment (such as the from the browser with Uppy). You can enable Signature Authentication from your Workspace Settings.

With Signature Authentication enabled, your Workspace's Auth Secret (found next to your Auth Key on the Credentials page) is then used to salt a hash generated from the request body, which contains both a key (which is your Auth Key as mentioned earlier), and an expires param, which is a timestamp in the near future used as an expiry date for the request.

We also recommend to include a randomly generated nonce with each request, in order to prevent signature re-use and defend against replay attacks. It's important to note that the nonce needs to be unique for each request, otherwise it's ineffective.

Note: For more details on how to generate a correctly hashed signature, take a look at our detailed guide on best practices.

The full request should look similar to the below:

{
  "params": {
    "auth": {
        "key": "23c96d084c744219a2ce156772ec3211",
        "expires": "2024/01/31 16:53:14+00:00",
        "nonce": "B6gT9zYMAzYOujKRMSaQT0GXL4XgLFDf",
    },
    "steps": { ... },
  },
  "signature": "9cf67cbba601e37ee10c442b037e0",
}

Once the request was received by Transloadit, we also generate a signature following the same process, and compare the two signatures. If the signatures are different, then our servers will respond with INVALID_SIGNATURE.

In summary, the process is as follows:

Generate a JSON payload to send to Transloadit as the params field.
Calculate a signature based off the contents of the payload, using your Auth Secret as a key.
Send the request to Transloadit, with the signature passed in the signature field
Transloadit will calculate the same signature using your account's Auth Secret, and the contents of the payload.
If the signatures match, the request is permitted, and an appropriate response is sent. Otherwise, the request is denied, and an error will be returned with the code INVALID_SIGNATURE.

This allows both parties to verify the other is authenticated (since a third party couldn't calculate a matching signature without access to your Auth Secret), without ever directly transmitting the Auth Secret.

Below are a few examples of how to perform a POST request to create an Assembly using a variety of methods. Although, we still suggest integrating with one of our SDKs in production apps, where possible.

curl --location 'https://api2.transloadit.com/assemblies' \
	--form 'params="{\"auth\":{\"key\":\"\23c96d084c744219a2ce156772ec3211\",\"expires\":\"2024/02/28 15:09:32.941Z\"},\"template_id\":\"\9cf67cbba601e37ee10c442b037e0\"}"' \
	--form 'signature="46253af0d7b2f0603375bbc6bfd5393363a8138c"' \
	--form 'files=@/path/to/your/file.jpg'

<!--
  We'll be inlining the following Assembly Instructions into a hidden params field,
  escaping HTML entities such as &lt;, a task best left to machines :)

  {
    "redirect_url": "https://example.com/success",
    "auth": {
      "key": "YOUR_TRANSLOADIT_KEY"
    },
    "template_id": "YOUR_TEMPLATE_ID",
    "steps": {}
  }
-->

<form
  method="POST"
  enctype="multipart/form-data"
  action="https://api2.transloadit.com/assemblies"
>
  <input
    type="hidden"
    name="params"
    value="%7B%0A%20%20%22redirect_url%22%3A%20%22https%3A%2F%2Fexample.com%2Fsuccess%22%2C%0A%20%20%22auth%22%3A%20%7B%0A%20%20%20%20%22key%22%3A%20%22YOUR_TRANSLOADIT_KEY%22%0A%20%20%7D%2C%0A%20%20%22template_id%22%3A%20%22YOUR_TEMPLATE_ID%22%2C%0A%20%20%22steps%22%3A%20%7B%7D%0A%7D"
  >
  <input type="file" name="myfile_1" multiple="multiple">
  <input type="submit" value="Upload">
</form>

const formdata = new FormData()
formdata.append(
  'params',
  '{"auth":{"key":"23c96d084c744219a2ce156772ec3211","expires":"2024/02/28 15:09:32.941Z"},"template_id":"9cf67cbba601e37ee10c442b037e0"}',
)
formdata.append('signature', '46253af0d7b2f0603375bbc6bfd5393363a8138c')
formdata.append('files', '/path/to/your/file.jpg')

const requestOptions = {
  method: 'POST',
  body: formdata,
  redirect: 'follow',
}

fetch('https://api2.transloadit.com/assemblies', requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error))

Does Transloadit include signatures with its requests?

Yes, Signature Authentication is two-way, meaning that we will also provide a signature for any requests we send to you, so that you can verify the authenticity of any request received by your servers. For example, a signature is included as part of requests sent from Assembly Notifications, generated using the same process as described above. We recommend you perform a similar check on any requests received from us, so that your code won't act on requests by just anyone.

Why cant I pass my Auth Secret as part of the `Bearer` token?

As part of cryptographic standards, your Auth Secret should never be transmitted as part of the request, and instead is only used as a salt for the signature hash. This ensures a malicious actor can't intercept the request and spoof requests to your account using your secret. Therefore, we recommend keeping your Auth Secret safe, by only storing it on your back-end - using whichever secret management system you prefer. Examples are: Vault, AWS Secrets Manager, GCP Secret Manager, and Kubernetes Secrets, but there are many more that could be suitable depending on your back-end platform of choice.

Note: You should ensure that Auth Secrets are never included as part of the front-end of your application, or exposed to users.

What order do the keys in the body need to be in?

The order you choose for the keys in the body can be arbitrary, however it's important to note that whichever order you choose needs to be consistent with your signature generation. The hash generated depends on the contents of the JSON, and a different ordering will generate a different hash, meaning your request will be denied.