authenticate

API reference for the authenticate method.

The authenticate method:

Triggers the start of an authentication flow
Returns the result of the authentication flow

Apps can use this method to let users authenticate with a third-party platform. The app can then provide the user with access to privileged content and features.

To learn more, see Starting an authentication flow.

Usage

import { getAuthentication } from "@canva/authentication";

(async () => {
  const authentication = getAuthentication();
  const result = await authentication.authenticate();
  switch (result.type) {
    case "authenticated":
      console.log("You authenticated!");
    case "canceled":
      console.log("You exited the authentication flow.");
    case "denied":
      console.log("You don't have the required permissions.");
    case "failed":
      console.log("Something went wrong.");
  }
})();

Parameters

#optionsobject

Optional

Options for customizing the authentication flow.

#options.contextstring

Optional

An arbitrary string that's appended to the app's Redirect URL during the authentication flow. The app can then access this value via its backend.

Returns

Returns a Promise that contains an authentication result:

#resultobject

Required

The result of the authentication flow.

#result.typestring

Required

A value that identifies if the authentication flow was successful or not.

This property may contain any of the following values:

"authenticated" - The user successfully authenticated.
"canceled" - The user canceled the authentication flow.
"denied - The user didn't have the required permissions.
"failed" - An unrecoverable error occurred.

When type is "denied", a details property is included in the object. This property is an array of strings that contains one or more error codes. The app can provide these error codes when redirecting the user back to Canva at the end of an authentication flow.

When type is "failed", a reason property is included in the object. This property is a string that contains a Canva-provided error code that identifies what went wrong.

Error codes

When type is "failed", the reason property may contain any of the following error codes:

invalid_context

The value of the context property is invalid.

invalid_options

The provided options for the authenticate method are invalid.

invalid_redirect_parameters

The query string parameters when redirecting back to Canva at the end of an authentication flow are invalid.

The query string parameters are invalid if any of the following things are true:

The state parameter is missing
The success parameter is missing
The success parameter is not "true" or "false"

invalid_redirect_url

The app's Redirect URL is invalid.

The Redirect URL may be considered invalid if it exceeds 2048 characters. This is a limitation of some web browsers. Be aware that, even if the original Redirect URL has a valid length, the parameters that Canva appends may cause it to exceed this length.

offline

The user tried to start an authentication flow while offline.

popup_is_not_available

Canva couldn't open the authentication popup window.

signature_verification_failed

The app's Redirect URL hasn't implemented signature verification correctly.

unknown

Something unexpected happened, such as an internal Canva error.