oauth

Changed on

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

Requests to this endpoint require authentication with your client ID and client secret, using one of the following methods:

  • Basic access authentication (Recommended): For basic access authentication, the {credentials} string must be a Base64 encoded value of {client id}:{client secret}.
  • Body parameters: Provide your app's credentials using the client_id and client_secret body parameters.

This endpoint can't be called from a user's web-browser client because it uses client authentication with client secrets. Requests must come from your app's backend, otherwise they'll be blocked by Canva's Cross-Origin Resource Sharing (CORS) policy.

post/v1/oauth/introspect

Request

  • Base URL: https://api.canva.com/auth
  • URL: https://api.canva.com/auth/v1/oauth/introspect
  • Auth: one of:
    • none
    • HTTP basic

Request body application/x-www-form-urlencoded

tokenstring required

The token to introspect.

client_idstring

Your app's unique ID, for authenticating the request.

NOTE: We recommend that you use basic access authentication instead of specifying client_id and client_secret as body parameters.

client_secretstring

Your app's client secret, for authenticating the request. Begins with cnvca.

NOTE: We recommend that you use basic access authentication instead of specifying client_id and client_secret as body parameters.

Example request

{
  "token": "JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo",
  "client_id": "OC-FAB12-AbCdEf",
  "client_secret": "cnvcaAbcdefg12345_hijklm6789"
}

Response

OK

activeboolean required

Whether the access token is active.

If true, the access token is valid and active. If false, the access token is invalid.

scopestring

The scopes that the token has been granted.

clientstring

The ID of the client that requested the token.

expinteger

The expiration time of the token, as a Unix timestamp in seconds.

iatinteger

When the token was issued, as a Unix timestamp in seconds.

nbfinteger

The "not before" time of the token, which specifies the time before which the access token most not be accepted, as a Unix timestamp in seconds.

jtistring

A unique ID for the access token.

substring

The subject of the claim. This is the ID of the Canva user that the access token acts on behalf of.

This is an obfuscated value, so a single user has a unique ID for each app. If the same user authorizes another app, their ID in that other app is different.

Example response

{
  "active": true,
  "scope": "asset:read design:meta:read design:permission:read folder:read",
  "client": "OC-FAB12-AbCdEf",
  "exp": 1712216144,
  "iat": 1712201744,
  "nbf": 1712201744,
  "jti": "AbC1d-efgHIJKLMN2oPqrS",
  "sub": "oBCdEF1Gh2i3jkLmno-pq"
}

Changes

  • 40ca7f6a753bRevision changes
    • warning

      added the new user_linked_to_another_idp enum value to the response property for the response status

    • warning

      added the new user_linked_to_another_idp enum value to the response property for the response status

    • warning

      added the new user_linked_to_another_idp enum value to the response property for the response status

  • 5ea5a3f48e72Revision changes
    • warning

      added the new asset_not_ready enum value to the response property for the response status

    • warning

      added the new asset_not_ready enum value to the response property for the response status

    • warning

      added the new asset_not_ready enum value to the response property for the response status