Signing requests

Every API call must be digitally signed with your API key. In combination with the session identifier, this allows us to verify you are authorised to make the API calls with the account you are attempting to access. The API key itself is never transmitted along with the requests and it is used solely during digital signing. To sign a request:

1. Sort the parameters by their parameter names in ascending ASCII order (case sensitive).
2. In that order, build the parameters into a URL-encoded query string, each key-value pair separated by an ampersand (&). The encoding must be performed per RFC 1738, which implies that spaces are encoded as plus (+) signs. This is the default for functions like PHP's http_build_query and Python's urllib.urlencode or urllib.parse.urlencode.
3. Use the SHA256 hashing algorithm to calculate an HMAC digest, using the query string from step 2 as input and your API key as the secret cryptographic key.

Example

The following is an example of a request to create a new certificate, with two Subject Altername Names. Be aware that there is a difference between specifying an empty string for a parameter and leaving out the parameter entirely. Both are usually acceptable, except in case of the Subject Alternate Names. If no SANs are required, the parameter musts not be passed to the API endpoint at all.

{
	"token" : "d7dd6880c206216a9ed74f92ca8edaef88728bbb2c8b23020c624de9a7d08d6f",
	"ca_id" : 123,
	"CN" : "example.com",
	"O" : "ACME, Inc.",
	"OU" : "IT Department",
	"C" : "US",
	"ST" : "Illinois",
	"L" : "Chicago",
	"SANs" : [
		{ "DNS" : "www.example.com" },
		{ "DNS" : "example.com" }
	]
}

After sorting, this will be:

{
	"C" : "US",
	"CN" : "example.com",
	"L" : "Chicago",
	"O" : "ACME, Inc.",
	"OU" : "IT Department",
	"SANs" : [
		{ "DNS" : "www.example.com" },
		{ "DNS" : "example.com" }
	],
	"ST" : "Illinois",
	"ca_id" : 123,
	"token" : "d7dd6880c206216a9ed74f92ca8edaef88728bbb2c8b23020c624de9a7d08d6f"
}

The SANs array is considered a numerically indexed array of associative arrays. In this example, the variable names for the two values will be SANs[0][DNS] and SANs[1][DNS], URL encoded to SANs%5B0%5D%5BDNS%5D and SANs%5B1%5D%5BDNS%5D respectively. The resulting encoded query string will be:

C=US&CN=example.com&L=Chicago&O=ACME%2C+Inc.&OU=IT+Department&SANs%5B0%5D%5BDNS%5D=www.example.com&SANs%5B1%5D%5BDNS%5D=example.com&ST=Illinois&ca_id=123&token=d7dd6880c206216a9ed74f92ca8edaef88728bbb2c8b23020c624de9a7d08d6f

Given an API key of ThisIsMySuperSecretAPIKey, the SHA256 HMAC would be:

16b436bd8779dadf0327a97eac54b631e02c4643cbf52ccc1358431691f74b21

When making the API call, this HMAC must be passed as an additional parameter named digest. If the digest parameter is not passed, the API call will fail with an HTTP 400 status and error code MissingParameter. If the digest has been calculated incorrectly, either due to a coding mistake or because of an incorrect API key, the HTTP status will be 403, with error code SignatureFailure.