This version of the API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Initializes an OAuth client for a multi account.

Parameters

optionsInitMultiAccountOauthOptions

Required

Options for initializing the oauth client

providerstring

Required

The provider to initialize the oauth client for

typestring

Required

The type of oauth client to initialize

The only valid value is "multi_account".

Returns

A client for authorizing users with OAuth.

requestAuthorizationfunction

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.

The only valid value is "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.

The only valid value is "aborted".

Examples

Start an authorization flow

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// 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({ type: 'multi_account' });

// 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
}

getAccountsfunction

Returns

The result of requesting a list of accounts. This is a Promise that resolves with the following object:

accountsOauthAccount[]

A client for managing a single OAuth account.

idstring

The ID of the account.

displayNamestring

The display name of the account.

expiredboolean

Whether the access token for the account has expired and there is no associated refresh token.

getAccessTokenfunction

Gets the access token and scopes for the current OAuth account.

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 OAuth account.

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 OAuth account, or null if the account 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 OAuth account

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get the account
const account = await oauth.getAccount({ accountId: '123' });

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

Check if the account is authorized

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get an access token for the account
const account = await oauth.getAccount({ accountId: '123' });
const token = await account.getAccessToken();

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

Forcefully refresh an access token

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get the account
const account = await oauth.getAccount({ accountId: '123' });

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

deauthorizefunction

Deauthorizes the account.

Returns

An empty Promise that resolves once the account is deauthorized.

Promise<void>

Example: Deauthorize an authorized account

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get the account
const account = await oauth.getAccount({ accountId: '123' });

// Deauthorize the account
await account.deauthorize();

principalstring

Optional

The principal of the account (e.g., email, username).

avatarUrlstring

Optional

The avatar URL of the account.

getAccountfunction

Parameters

requestGetAccountRequest

Required

Options for requesting a single OAuth account.

accountIdstring

Required

Returns

The result of requesting a single account. This is a Promise that resolves with the following object:

accountOauthAccount

A client for managing a single OAuth account.

idstring

The ID of the account.

displayNamestring

The display name of the account.

expiredboolean

Whether the access token for the account has expired and there is no associated refresh token.

getAccessTokenfunction

Gets the access token and scopes for the current OAuth account.

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 OAuth account.

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 OAuth account, or null if the account 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 OAuth account

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get the account
const account = await oauth.getAccount({ accountId: '123' });

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

Check if the account is authorized

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get an access token for the account
const account = await oauth.getAccount({ accountId: '123' });
const token = await account.getAccessToken();

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

Forcefully refresh an access token

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get the account
const account = await oauth.getAccount({ accountId: '123' });

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

deauthorizefunction

Deauthorizes the account.

Returns

An empty Promise that resolves once the account is deauthorized.

Promise<void>

Example: Deauthorize an authorized account

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

// Initialize an OAuth client
const oauth = auth.initOauth({ type: 'multi_account' });

// Get the account
const account = await oauth.getAccount({ accountId: '123' });

// Deauthorize the account
await account.deauthorize();

principalstring

Optional

The principal of the account (e.g., email, username).

avatarUrlstring

Optional

The avatar URL of the account.