CTRL + K

Access restriction

Direct API access can be restricted in your dashboard under project settings. One of the following settings can be selected:

Restricted: This is the default. A Direct API request can only be made for templates that exist in your project. If you want to use the source parameter, you have to sign your URL.
Unprotected: When this setting is enabled, the Direct API will accept all requests without requiring a signed URL. It is recommended that you do not enable this on public facing URLs because it allows anyone to create renders on your account.
Protected: The Direct API accepts only requests that are signed with a HMAC-SHA256 hash.

As the email personalization feature relies on the Direct API, setting the access option to "Protected" prevents you from using the provided personalized URL examples since they lack a signature.

Securing a Direct API request

If you set Direct API access to Protected in project settings, you must sign your URL with an HMAC-SHA256 signature using your API key. This also applies if you use the source parameter with Restricted access. This hash is computed over the full URL, and then appended, as shown in the example below:

https://api.creatomate.com/v1/direct?template_id=b3680d7c-4a65-4f5b-bf52-adbf8a63a5a4&output_format=gif&signature=YOUR_SIGNATURE

Node.js example

1const crypto = require("crypto");
2
3const apiKey = "YOUR_API_KEY_HERE";
4const exampleUrl = "https://api.creatomate.com/v1/direct?template_id=b3680d7c-4a65-4f5b-bf52-adbf8a63a5a4&output_format=gif";
5const signature = crypto.createHmac("sha256", apiKey).update(exampleUrl).digest("hex");
6const signedUrl = exampleUrl + "&signature=" + signature;
7

PHP example

1<?php
2$api_key = "YOUR_API_KEY_HERE";
3$example_url = "https://api.creatomate.com/v1/direct?template_id=b3680d7c-4a65-4f5b-bf52-adbf8a63a5a4&output_format=gif";
4$signature = hash_hmac("sha256", $example_url, $api_key);
5$signed_url = $example_url . "&signature=" . $signature;
6

Python example

1import hmac
2import hashlib
3
4api_key = "YOUR_API_KEY_HERE"
5example_url = "https://api.creatomate.com/v1/direct?template_id=b3680d7c-4a65-4f5b-bf52-adbf8a63a5a4&output_format=gif"
6signature = hmac.new(api_key.encode('utf-8'), example_url.encode('utf-8'), hashlib.sha256).hexdigest()
7signed_url = example_url + "&signature=" + signature
8

Ruby example

1require "openssl"
2
3api_key = "YOUR_API_KEY_HERE"
4example_url = "https://api.creatomate.com/v1/direct?template_id=b3680d7c-4a65-4f5b-bf52-adbf8a63a5a4&output_format=gif"
5signature = OpenSSL::HMAC.hexdigest("SHA256", api_key, example_url)
6signed_url = example_url + "&signature=" + signature
7

URL format