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 ( ) ;
A client for authorizing users with OAuth.
requestAuthorization
function
Starts an OAuth authorization flow.
Parameters
request
AuthorizationRequest<T>
Optional View type definition Options for configuring the authorization flow.
queryParams
ExcludeKeys<T, ForbiddenKey>
Optional View type definition 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"
scope
Set<string>
Optional View type definition 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:
AuthorizationCompleted AuthorizationCompleted
AuthorizationAborted AuthorizationAborted
The result when a user successfully completes an OAuth authorization flow.
The status of the authorization flow.
This must be "completed"
.
The scopes associated with the user.
The result when a user fails to complete an OAuth authorization flow.
The status of the authorization flow.
This must be "aborted"
.
Examples
Start an authorization flow
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const response = await oauth . requestAuthorization ( ) ;
Start an authorization flow with specific scopes
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const scope = new Set ( [ 'PLACEHOLDER_SCOPE_1' , 'PLACEHOLDER_SCOPE_2' ] ) ;
const response = await oauth . requestAuthorization ( { scope } ) ;
Start an authorization flow with custom query parameters
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const queryParams = new Map ( [ [ 'custom_param' , 'custom_value' ] ] ) ;
const response = await oauth . requestAuthorization ( { queryParams } ) ;
Handle the result of a authorization flow
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const response = await oauth . requestAuthorization ( ) ;
if ( response . status === 'completed' ) {
}
if ( response . status === 'aborted' ) {
}
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
request
AccessTokenRequest
Optional View type definition Options for requesting an access token for the current user.
forceRefresh
boolean
Optional View type definition If true
, the access token will be refreshed, even if it hasn't expired.
By default, access tokens are automatically refreshed after expiry.
scope
Set<string>
Optional View type definition 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:
The access token for the current user.
The scopes associated with the current user's access token.
Examples
Get the access token of the current user
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const token = await oauth . getAccessToken ( ) ;
Check if the user is authorized
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const token = await oauth . getAccessToken ( ) ;
if ( token ) {
} else {
}
Forcefully refresh an access token
import { auth } from "@canva/user" ;
const oauth = auth . initOauth ( ) ;
const token = await oauth . getAccessToken ( { forceRefresh : true } ) ;
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" ;
const oauth = auth . initOauth ( ) ;
await oauth . deauthorize ( ) ;
Rate limit
This method has a rate limit of 10 requests every 10 seconds.