Ending an authentication flow

Once a user has finished authenticating, an app needs to end the authentication flow by closing the popup window and refreshing the app's UI to reflect the user's authentication status.

This guide explains how to end an authentication flow.

Step 1: Redirect the user back to Canva

Within the popup window, redirect the user to the following URL:

https://www.canva.com/apps/configured

The redirect itself must be a 302 redirect. Other status codes are not accepted.

The app must also append the following query parameters to the URL:

• success
• state

The value of the success parameter indicates whether or not the user authenticated successfully. This should be set to "true" if the authentication was successful and "false" if the authentication was not successful.

The value of the state parameter must contain the value of the state token that Canva appended to the Redirect URL at the start of the authentication flow. This protects the app against CSRF attacks.

The following snippet demonstrates how to implement this redirect with Express.js:

const params = new URLSearchParams({
  success: "true",
  state: "STATE_TOKEN_GOES_HERE",
});

response.redirect(302, `https://www.canva.com/apps/configured?${params}`);

Step 2: Handle the authentication result

When the redirect completes:

• The popup window closes.
• The authenticate method returns an AuthenticationResult object.

The AuthenticationResult object has a type property that describes the result of the authentication flow. The possible values include:

• succeeded - The authentication was successful.
• denied - The authentication was unsuccessful.
• canceled - The user closed the popup window without completing the authentication flow.
• failed - A non-recoverable error occurred.

An app can use the type property to determine the UI it should render.

(Optional) Step 3: Pass a custom error code

If a user fails to authenticate, you may want to provide them with more context about what went wrong. To do this, append an errors parameter to the redirect:

const params = new URLSearchParams({
  success: "false",
  state: "STATE_TOKEN_GOES_HERE",
  errors: "ERROR_CODE_ONE,ERROR_CODE_TWO",
});

response.redirect(302, `https://www.canva.com/apps/configured?${params}`);

This parameter accepts a comma-separated list of error codes.

When the authenticate method returns an AuthenticationResullt object, the app can access the error codes via the details property:

const result = await auth.authenticate();
console.log(result);
// {
//     type: "denied",
//     errors: ["ERROR_CODE_ONE", "ERROR_CODE_TWO"]
// }

The app can then implement certain behavior or render a certain UI based on the specific error code(s).