Skip navigation

Skip to main content

API reference
Intents: design
API reference

auth.initOauth

API reference for the auth.initOauth method.
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.

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();
TS

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 });
TS

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 });
TS

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
}
TS
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();
TS

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

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 });
TS
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();
TS