Sending requests

Apps can use the Fetch API to send requests to a backend. This allows apps to offload tasks to a server, rather than trying to handle complex or long-running tasks in the browser.

For the sake of security, we require that apps verify the legitimacy of any requests they receive via their backend. This guide explains how to send and verify HTTP requests.

Step 1: Start the local development servers

The lifecycle of an HTTP request relies on interactions between:

• The frontend of the app, which sends the request and receives a response.
• The backend of the app, which handles the request and verifies that it's from a legitimate source.
• Canva's backend, which generates a JSON Web Token (JWT) for verifying a request's legitimacy.

In the starter kit, we've included an example of an app that communicates with a backend.

To start the development servers for this example:

1. Copy the ID of an app from the Your apps page.

2. In the starter kit's .env file, set CANVA_APP_ID to the ID of the app.

3. Run the following command:

   npm start fetch

The example in the starter kit communicates with a local, mocked version of the Canva backend. The purpose of this Canva backend is to generate a JWT before sending a request. The request itself is not routed through Canva's backend — it's sent directly from the app's frontend, to the app's backend.

A mocked version of the Canva backend is required because the actual backend hasn't launched yet. When the actual backend for Canva is ready, the app can be updated to point to Canva's server.

Step 2: Get a JWT from Canva

Before an app sends an HTTP request to its backend, it must request a JWT from Canva. The app's backend can use this token to verify that the request is legitimate.

To get a JWT, initialize the Authentication capability:

import { getAuthentication } from "@canva/authentication";
const auth = getAuthentication();

Then call the getCanvaUserToken method:

const token = await auth.getCanvaUserToken();

For the time being, this method sends a request to the mock server. This means it's essential that the mock server is running. In the future, the request will be sent to Canva's actual backend.

Step 3: Send a request with the Authorization header

To send a request to the app's backend, call the fetch method and include an Authorization header that contains the JWT returned by the getCanvaUserToken method:

const response = await fetch("http://localhost:3001/custom-route", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

For the request to succeed, the backend must decode the JWT and verify that it's valid. If you're using the backend server in the starter kit example, this is automatically handled for you.

To learn how to create a backend that can decode and verify JWTs, see Verifying requests.

(Optional) Step 4: Get the ID of the user and their team

In the app's backend, the payload of the decoded JWT contains the ID of the user and their team. In the starter kit examples, these values are made available via a response.locals object:

app.get("/custom-route", (request, response) => {
  console.log(response.locals.userId);
  console.log(response.locals.brandId);
});

An app can use these values to provide content or features that are tailored to individual users. To learn more, see Authentication.