Verify GET request signatures

When Canva sends a GET request to an app, it includes a comma-separated list of request signatures in the signatures query parameter.
A request signature is a unique string of characters that identifies the request:
1
e03c80881a48bb730cee12c7e842301b0b116b970a03068a5f5263358926e897
Copied!
Before you can submit an app for review, the app must:
1.Calculate a signature for each request.
2.Check if the calculated signature is found in the comma-separated list of signatures.
3.Return a 401 status code if the calculated signature is not in the list of signatures.
This protects the app from a variety of attacks.
Canva provides a list of signatures—rather than just one signature—to support key rotation. This lets you regenerate client secrets without causing downtime.
Step 1: Get your app's client secret
Every app has a client secret. This is a sensitive value that's shared between Canva and your app. You must use the secret to calculate a request signature.
To get your app's client secret:
1.Navigate to an app via the Developer Portal.
2.Click Verification.
3.Under the Client secret heading, click Copy.
Never share a client secret or commit it to source control.
We recommend loading the client secret via an environment variable.
Step 2: Decode your app's client secret
Canva provides the Client secret as a base64-encoded string. Your app must decode this string into a byte array. The following snippet demonstrates how to do this in Node.js:
1
const secret = process.env.CLIENT_SECRET;
2
const key = Buffer.from(secret, "base64");
3
console.log(key);
Copied!
To learn how to decode a client secret in different programming languages, refer to Decoding a client secret.
Step 3: Create a message
To verify that a request signature was generated by Canva, an app must calculate the signature itself and compare it to the provided signatures. This requires two ingredients: a key and a message.
The key is the decoded client secret.
In a GET request, the message is a colon-separated string that contains the following values:
Version
The version of Canva's API that's sending the request. You must set this value to v1.
Timestamp
The UNIX timestamp (in seconds) of when Canva sent the request. You can access this timestamp via the time query parameter.
User
The ID of the user. You can access this ID via the user query parameter.
Brand
The ID of the user's brand. You can access this ID via the brand query parameter.
Extensions
A comma-separated list of extension types, such as CONTENT or PUBLISH. You can access this list via the extensions query parameter.
State
A unique token for protecting an app against CSRF attacks. You can access this token via the state query parameter.
This snippet demonstrates how to construct a message for a GET request:
1
const express = require("express");
2
const app = express();
3
​
4
app.get("/my-redirect-url", async (request, response) => {
5
  const version = "v1";
6
  const { time, user, brand, extensions, state } = request.query;
7
  const message = `${version}:${time}:${user}:${brand}:${extensions}:${state}`;
8
  console.log(message);
9
});
10
​
11
app.listen(process.env.PORT || 3000);
Copied!
This is an example of a message for a GET request:
1
v1:1586167939:AQy_Xvglh9cbgHk97BqOiRscRk98Vm-Fjytfs9X-68s=:AQy_XvgNXCsnKeFtcD5-L-VBg_ngJepbEhGYBVmCo6E=:CONTENT:95a5aa62-0713-4ae4-b99f-8efa57e7def0
Copied!
Step 4: Calculate the request signature
When you have a key and a message, use these values to calculate a SHA-256 hash and convert that hash into a hex-encoded string. The result is the signature of the request.
This snippet demonstrates how to calculate a signature in Node.js:
1
const { createHmac } = require("crypto");
2
const signature = createHmac("sha256", key).update(message).digest("hex");
3
console.log(signature);
Copied!
You can refactor this logic into a calculateSignature function that accepts a secret and a message and returns a signature:
1
function calculateSignature(secret, message) {
2
  // Decode the client secret
3
  const key = Buffer.from(secret, "base64");
4
​
5
  // Generate the signature
6
  return createHmac("sha256", key).update(message).digest("hex");
7
}
Copied!
You can then use this function to calculate the signature for GET and POST requests.
Step 5: Compare the signatures
When Canva sends a GET request to an app, it includes a comma-separated list of request signatures in the signatures query parameter.
If the calculated signature is not included in the list of signatures, the request did not originate from Canva and the app must reject the request with a 401 status code:
1
// Load the client secret from an environment variable
2
const secret = process.env.CLIENT_SECRET;
3
​
4
// Construct the message
5
const version = "v1";
6
const { time, user, brand, extensions, state } = request.query;
7
const message = `${version}:${time}:${user}:${brand}:${extensions}:${state}`;
8
​
9
// Calculate a signature
10
const signature = calculateSignature(secret, message);
11
​
12
// Reject requests with invalid signatures
13
if (!request.query.signatures.includes(signature)) {
14
  response.sendStatus(401);
15
  return;
16
}
Copied!
Step 6: Verify the timestamp
Even if an app verifies request signatures, it's still vulnerable to replay attacks. To protect itself against these types of attacks, an app must:
1.Compare the timestamp of when the request was sent with when it was received.
2.Verify that the timestamps are within 5 minutes (300 seconds) of one another.
When the timestamps are not within 5 minutes of one another, the app must reject the request by returning a 401 status code.
In a GET request, an app can access the UNIX timestamp (in seconds) of when Canva sent the request via the time query parameter.
The following snippet demonstrates how to create an isValidTimestamp function that checks if two timestamps are within 300 seconds of each other and rejects the request if they're not:
1
function isValidTimestamp(
2
  sentAtSeconds,
3
  receivedAtSeconds,
4
  leniencyInSeconds = 300
5
) {
6
  return (
7
    Math.abs(Number(sentAtSeconds) - Number(receivedAtSeconds)) <
8
    Number(leniencyInSeconds)
9
  );
10
}
11
​
12
const sentAtSeconds = request.query.time;
13
const receivedAtSeconds = new Date().getTime() / 1000;
14
​
15
// Verify the timestamp of a POST request
16
if (!isValidTimestamp(sentAtSeconds, receivedAtSeconds)) {
17
  response.sendStatus(401);
18
  return;
19
}
Copied!
The leniency of 5 minutes accounts for the fact that requests are not instantaneous and server clocks may not be perfectly synchronized.
Example
1
const { createHmac } = require("crypto");
2
const express = require("express");
3
​
4
const app = express();
5
​
6
app.get("/my-redirect-url", async (request, response) => {
7
  if (!isValidGetRequest(process.env.CLIENT_SECRET, request)) {
8
    response.sendStatus(401);
9
    return;
10
  }
11
​
12
  response.sendStatus(200);
13
});
14
​
15
const isValidGetRequest = (secret, request) => {
16
  // Verify the timestamp
17
  const sentAtSeconds = request.query.time;
18
  const receivedAtSeconds = new Date().getTime() / 1000;
19
​
20
  if (!isValidTimestamp(sentAtSeconds, receivedAtSeconds)) {
21
    return false;
22
  }
23
​
24
  // Construct the message
25
  const version = "v1";
26
  const { time, user, brand, extensions, state } = request.query;
27
  const message = `${version}:${time}:${user}:${brand}:${extensions}:${state}`;
28
​
29
  // Calculate a signature
30
  const signature = calculateSignature(secret, message);
31
​
32
  // Reject requests with invalid signatures
33
  if (!request.query.signatures.includes(signature)) {
34
    return false;
35
  }
36
​
37
  return true;
38
};
39
​
40
const isValidTimestamp = (
41
  sentAtSeconds,
42
  receivedAtSeconds,
43
  leniencyInSeconds = 300
44
) => {
45
  return (
46
    Math.abs(Number(sentAtSeconds) - Number(receivedAtSeconds)) <
47
    Number(leniencyInSeconds)
48
  );
49
};
50
​
51
const calculateSignature = (secret, message) => {
52
  // Decode the client secret
53
  const key = Buffer.from(secret, "base64");
54
​
55
  // Calculate the signature
56
  return createHmac("sha256", key).update(message).digest("hex");
57
};
58
​
59
app.listen(process.env.PORT || 3000);
Copied!

Verify POST request signatures

Verify timestamp

Last modified 6mo ago

Copy link

Contents

Step 1: Get your app's client secret

Step 2: Decode your app's client secret

Step 3: Create a message

Step 4: Calculate the request signature

Step 5: Compare the signatures

Step 6: Verify the timestamp

Example