Starting an authentication flow

An authentication flow is the series of steps a user must go through to authenticate with an app. Canva doesn't enforce any particular authentication method, so the steps themselves are at the discretion of the app. The only requirements relate to how an app starts (and ends) an authentication flow.

This guide explains how an app can start an authentication flow.

Prerequisites

• You've set up a Redirect URL.
• You've enabled authentication.

Step 1: Initialize the Authentication capability

Like all capabilities, Canva injects the Authentication capability into the app's iframe and attaches it to the window object:

console.log(window.canva.authentication);

You can access the capability by importing and calling the getAuthentication function:

import { getAuthentication } from "@canva/authentication";
const auth = getAuthentication();
console.log(auth); // => Authentication

This function:

• Throws an error if the capability is unavailable
• Provides type-safety when using TypeScript

Step 2: Call the authenticate method

Apps can trigger the start of an authentication flow at any point in its lifecycle, such as when a user clicks a button or if a user tries to access restricted content.

The following screenshot demonstrates a common pattern for prompting users to authenticate:

To trigger an authentication flow, call the authenticate method:

const result = await auth.authenticate();

This is an asynchronous method that opens a popup window and, within this window, redirects the user to the app's Redirect URL:

Authentication flows must take place within the pop-up window. Apps are not allowed to embed the authentication flow (e.g. provide a sign up or login form) within the app's iframe.

In the popup window, the user can navigate through the app's authentication flow. Since the Redirect URL is hosted on the developer's infrastructure, the flow is under the complete control of the app.

To learn how to set up a Redirect URL, see Setting up a Redirect URL.

(Optional) Step 3: Pass data to the app's backend

Apps can pass a context property into the authenticate method:

const result = await auth.authenticate({
  context: "Hello world",
});

This property accepts a string that Canva then appends to the Redirect URL. You can use it to pass arbitrary data to an app's backend at the start of an authentication flow.

Here's a couple of examples of potential use-cases:

• The app authenticates with a third-party service that supports multiple authentication endpoints or custom domains. For example, a self-managed app like GitLab that organizations can host on their own domain. Users could customize the endpoint or domain within the app.
• The app needs to set different authentication permissions based on the user's actions. For example, the app may request access to a minimal set of scopes but let the user re-run the authentication flow to access additional scopes at a later time.