Authentication

To start using the Canva Connect API, you need to authenticate your users using OAuth 2.0.

OAuth authentication lets your integration authenticate the user, and get their authorization to access the Connect API endpoints and perform actions on their behalf. If you're already familiar with OAuth 2.0 – we're using the Authorization Code flow with PKCE using SHA-256.

An overview of the OAuth authentication process is shown below:

The authentication process involves the following steps:

1. Obtain authorization from the user for the scopes that your integration requires. After a user authorizes your integration, you'll receive an authorization code at your specified redirect URL.
2. Use the authorization code to generate access tokens to use in your API requests. This allows your integration to act on the user's behalf.

Prerequisites

Before authenticating to the Canva Connect API, you must first create and configure your integration in the Developer Portal, including:

• Generating and saving a client secret
• Selecting scopes
• Setting at least one authentication redirect URL

Obtain user authorization

To obtain user authorization, you must direct your users to Canva's authorization URL. This lets a user review and approve access for your integration.

Create the authorization URL

The authorization URL that you direct users to is in the following format:

https://www.canva.com/api/oauth/authorize?code_challenge=<code challenge string>&code_challenge_method=s256&scope=<list of scopes>&response_type=code&client_id=<client ID>&state=<optional state>&redirect_uri=<redirect uri for your integration>

The URL has the following query parameters:

An example authorization URL might look similar to the following:

https://www.canva.com/api/oauth/authorize?code_challenge=eeeAbcdefgh123456789Vz96F9UIv8EHwnmibz3Djx3EE&code_challenge_method=s256&scope=asset:read%20asset:write%20design:meta:read%20folder:read%20comment:write&response_type=code&client_id=OCABC12-DeF

Example code for code_verifier & code_challenge strings

You can use the following sample code to generate the code_verifier and code_challenge strings.

const crypto = require("crypto");
const randomBytes = crypto.randomBytes(32).toString("hex");
const codeVerifier = randomBytes.toString('base64url')
const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url")

Send the user to the authorization URL

You must direct your users to the authorization URL that you created to get their approval for your integration and the requested scopes.

They will see a prompt similar to the following:

After they authorize your integration, they are redirected to your redirect URL with the following query parameters:

Generate access tokens

After you've obtained user authorization and received an authorization code, you can exchange the code for an access token (that lets you act on the user's behalf) and a refresh token (that you can use to get new access tokens).

Because access tokens are only valid for a short period time, you can handle requesting new access tokens using a refresh token instead of having to re-authorize the user to get a new authorization code.

An overview of the token request process is shown in the diagram below:

Use an authorization code

To exchange an authorization code for an access token, use the Generate an access token endpoint.

Some points to note when using the endpoint with an authorization code:

• Requests to the endpoint require basic access authentication with your client ID as the username and your client secret as the password. For basic access authentication, the {credentials} string must be a Base64 encoded value of {client id}:{client secret}.
• When exchanging an authorization code for an access token, you must set grant_type to authorization_code .
• You must provide the code_verifier value that you generated when creating the user authorization URL.
• You must provide the authorization code you received after the user authorized your integration.

The endpoint reference includes example request code in various languages.

A successful response from the endpoint includes the access token, the expiry time for the token, and a refresh token.

Use a refresh token

When an access token expires or becomes invalid, you can use a refresh token from a previous access token request to get a new access token.

To exchange a refresh token for an access token, you again use the Generate an access token endpoint.

Some points to note when using the endpoint with a refresh token:

• Requests to the endpoint require basic access authentication with your client ID as the username and your client secret as the password. For basic access authentication, the {credentials} string must be a Base64 encoded value of {client id}:{client secret}.
• When exchanging a refresh token for a new access token, you must set grant_type to refresh_token.
• You must provide a refresh token from a previous token request.
• Each refresh token can only be used once.

A successful response from the endpoint includes a new access token, the expiry time for the new token, and another refresh token.

Introspect an access token

You can use the Introspect an access token endpoint to see whether an access token or refresh token is valid and active. You can also verify some token properties, such as its claims, scopes, and validity times.

Revoke an access token

If necessary, you can use the Revoke an access token endpoint to revoke an access token or refresh token.