API reference

Asset

getTemporaryUrl findFonts openColorSelector requestFontSelection upload

Design

addAudioTrack addElementAtCursor addElementAtPoint addNativeElement addPage createRichtextRange editContent getCurrentPageContext getDefaultPageDimensions getDesignToken initAppElement openDesign overlay.registerOnCanOpen requestExport selection.registerOnChange setCurrentPageBackground ui.startDragToCursor ui.startDragToPoint ui.startDrag

Intents: data

prepareDataConnector

Intents: design

prepareDesignEditor

Platform

appProcess appProcess.broadcastMessage appProcess.current appProcess.current.getInfo appProcess.current.requestClose appProcess.current.setOnDispose appProcess.requestClose appProcess.registerOnMessage appProcess.registerOnStateChange features.isSupported features.registerOnSupportChange getPlatformInfo notification.addToast requestOpenExternalUrl

User

auth.getCanvaUserToken auth.initOauth

API reference

auth.initOauth

API reference for the auth.initOauth method.

Creates a client for authenticating users with OAuth.

To learn more, see https://www.canva.dev/docs/apps/authenticating-users/oauth.

Usage: Initialize an OAuth client

import { auth } from '@canva/user';

const oauth = auth.initOauth();

TYPESCRIPT

Returns

A client for authorizing users with OAuth.

requestAuthorizationfunction

Starts an OAuth authorization flow.

Parameters

requestAuthorizationRequest<T>

Optional

Options for configuring the authorization flow.

queryParamsExcludeKeys<T, ForbiddenKey>

Optional

Query parameters to append to the URL of the request.

The following keys are not allowed in this object:

"client_id"
"redirect_uri"
"scope"
"state"
"response_type"
"code_challenge"
"code_challenge_method"
"client_secret"

scopeSet<string>

Optional

The list of scopes to request access to.

Returns

The result of the authorization flow. This is a Promise that resolves with the following object:

The result when a user successfully completes an OAuth authorization flow.

statusstring

The status of the authorization flow.

This must be "completed".

scopeSet<string>

The scopes associated with the user.

The result when a user fails to complete an OAuth authorization flow.

statusstring

The status of the authorization flow.

This must be "aborted".

Examples

Start an authorization flow

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Start an authorization flow
const response = await oauth.requestAuthorization();

Start an authorization flow with specific scopes

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Define the scopes to request
const scope = new Set(['PLACEHOLDER_SCOPE_1', 'PLACEHOLDER_SCOPE_2']);

// Start an authorization flow with specific scopes
const response = await oauth.requestAuthorization({ scope });

Start an authorization flow with custom query parameters

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Define the query parameters to append to the URL of the request
const queryParams = new Map([['custom_param', 'custom_value']]);

// Start an authorization flow with custom query parameters
const response = await oauth.requestAuthorization({ queryParams });

Handle the result of a authorization flow

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Start an authorization flow
const response = await oauth.requestAuthorization();

if (response.status === 'completed') {
 // The user completed the authorization flow
}

if(response.status === 'aborted') {
 // The user did not complete the authorization flow
}

getAccessTokenfunction

Gets the access token and scopes for the current user.

When a token expires, it's automatically refreshed by Canva.
The token is cached by Canva, so the app's frontend shouldn't store the token.

Parameters

requestAccessTokenRequest

Optional

Options for requesting an access token for the current user.

forceRefreshboolean

Optional

If true, the access token will be refreshed, even if it hasn't expired.

By default, access tokens are automatically refreshed after expiry.

scopeSet<string>

Optional

The scopes associated with the access token.

Returns

The access token and scopes for the current user, or null if the user isn't authorized. This is a Promise that resolves with either undefined or the following object:

tokenstring

The access token for the current user.

scopeSet<string>

The scopes associated with the current user's access token.

Examples

Get the access token of the current user

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Get an access token for the user
const token = await oauth.getAccessToken();

Check if the user is authorized

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Get an access token for the user
const token = await oauth.getAccessToken();

if (token) {
 // The user is authorized
} else {
 // The user is not authorized
}

Forcefully refresh an access token

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Forcefully refresh an access token
const token = await oauth.getAccessToken({ forceRefresh: true });

deauthorizefunction

Disconnects the user from the identity provider (IdP).

If token revocation is supported by the OAuth provider, the refresh and access tokens will be revoked.

Returns

An empty Promise that resolves once the user is disconnected from the IdP.

Promise<void>

Example: Disconnect an authorized user from the identity provider (IdP)

import { auth } from "@canva/user";

// Initialize an OAuth client
const oauth = auth.initOauth();

// Disconnect the user from the IdP
await oauth.deauthorize();

Rate limit

This method has a rate limit of 10 requests every 10 seconds.