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

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

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

// Check if the user has a token
const token = await oauth.getAccessToken();

// If an access token is available, the user is authorized
if (token) {
 // Use the token to implement behavior that requires authorization
 console.log(token);
} else {
 // Otherwise, start an authorization flow
 const response = await oauth.requestAuthorization();

 if (response.status === "complete") {
   // The user successfully authorized
   // The app can now get the user's access token
 } else {
   // The user did not successfully authorize
 }
}

Returns

A client for authorizing users with OAuth.

requestAuthorizationfunction

Starts an OAuth authorization flow.

Parameters

requestAuthorizationRequest<T>

OPTIONAL

Options for configuring the authorization flow.

Properties of request

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".

Example

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

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

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

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.

Properties of request

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.

Example

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 a token isn't available, the user isn't authorized
if (token) {
 // The user is authorized
 console.log(token);
} else {
 console.log("The user is not authorized.");
}

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

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

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

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