> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# Introspect an access token

Introspect a token to see its validity and properties.

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](https://en.wikipedia.org/wiki/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)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) policy.

## HTTP method and URL path

POST https\://api.canva.com/rest/v1/oauth/introspect

## Authentication and authorization

This endpoint uses HTTP basic access authentication.

## Header parameters

<Prop.List>
  <Prop name="Authorization" type="string">
    Provides credentials to authenticate the request, in the form of [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).

    For example: `Authorization: Basic {credentials}`

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

  <Prop name="Content-Type" type="string" required>
    Indicates the media type of the information sent in the request. This must be set to `application/x-www-form-urlencoded`.

    For example: `Content-Type: application/x-www-form-urlencoded`
  </Prop>
</Prop.List>

## Body parameters

<Prop.List>
  <Prop name="token" type="string" required>
    The token to introspect.
  </Prop>

  <Prop name="client_id" type="string">
    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.
  </Prop>

  <Prop name="client_secret" type="string">
    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.
  </Prop>
</Prop.List>

## Example request

Examples for using the `/v1/oauth/introspect` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request POST 'https://api.canva.com/rest/v1/oauth/introspect' \
    --header 'Authorization: Basic {credentials}' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo'
    ```
  </Tab>

  <Tab name="Node.js">
    ```js
    const fetch = require("node-fetch");
    const { URLSearchParams } = require("url");

    fetch("https://api.canva.com/rest/v1/oauth/introspect", {
      method: "POST",
      headers: {
        "Authorization": "Basic {credentials}",
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams("token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo"),
    })
      .then(async (response) => {
        const data = await response.json();
        console.log(data);
      })
      .catch(err => console.error(err));
    ```
  </Tab>

  <Tab name="Java">
    ```java
    import java.io.IOException;
    import java.net.URI;
    import java.net.http.*;

    public class ApiExample {
        public static void main(String[] args) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.canva.com/rest/v1/oauth/introspect"))
                .header("Authorization", "Basic {credentials}")
                .header("Content-Type", "application/x-www-form-urlencoded")
                .method("POST", HttpRequest.BodyPublishers.ofString("token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo"))
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );
            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab name="Python">
    ```py
    import requests

    headers = {
        "Authorization": "Basic {credentials}",
        "Content-Type": "application/x-www-form-urlencoded"
    }

    data = {
        "token": "JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo",
    }

    response = requests.post("https://api.canva.com/rest/v1/oauth/introspect",
        headers=headers,
        data=data
    )
    print(response.json())
    ```
  </Tab>

  <Tab name="C#">
    ```csharp
    using System.Net.Http;

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Post,
      RequestUri = new Uri("https://api.canva.com/rest/v1/oauth/introspect"),
      Headers =
      {
        { "Authorization", "Basic {credentials}" },
      },
      Content = new StringContent(
        "token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo",
        Encoding.UTF8,
        "application/x-www-form-urlencoded"
      ),
    };

    using (var response = await client.SendAsync(request))
    {
      response.EnsureSuccessStatusCode();
      var body = await response.Content.ReadAsStringAsync();
      Console.WriteLine(body);
    };
    ```
  </Tab>

  <Tab name="Go">
    ```go
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    	"strings"
    )

    func main() {
    	payload := strings.NewReader("token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo")

    	url := "https://api.canva.com/rest/v1/oauth/introspect"
    	req, _ := http.NewRequest("POST", url, payload)
    	req.Header.Add("Authorization", "Basic {credentials}")
    	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	body, _ := io.ReadAll(res.Body)
    	fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab name="PHP">
    ```php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.canva.com/rest/v1/oauth/introspect",
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Basic {credentials}',
        'Content-Type: application/x-www-form-urlencoded',
      ),
      CURLOPT_POSTFIELDS => "token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo"
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if (empty($err)) {
      echo $response;
    } else {
      echo "Error: " . $err;
    }
    ```
  </Tab>

  <Tab name="Ruby">
    ```ruby
    require 'net/http'
    require 'uri'

    url = URI('https://api.canva.com/rest/v1/oauth/introspect')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(url)
    request['Authorization'] = 'Basic {credentials}'
    request['Content-Type'] = 'application/x-www-form-urlencoded'
    request.body = "token=JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo"

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>
</Tabs>

## Success response

If successful, the endpoint returns a `200` response with a JSON body with the following parameters:

<Prop.List>
  <Prop name="active" type="boolean" required mode="output">
    Whether the access token is active.

    If `true`, the access token is valid and active. If `false`, the access token is invalid.
  </Prop>

  <Prop name="scope" type="string" mode="output">
    The [scopes](https://www.canva.dev/docs/apps/rest-apis/scopes/) that the token has been granted.
  </Prop>

  <Prop name="client" type="string" mode="output">
    The ID of the client that requested the token.
  </Prop>

  <Prop name="exp" type="integer" mode="output">
    The expiration time of the token, as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) in seconds.
  </Prop>

  <Prop name="iat" type="integer" mode="output">
    When the token was issued, as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) in seconds.
  </Prop>

  <Prop name="nbf" type="integer" mode="output">
    The "not before" time of the token, which specifies the time before which the access token most not be accepted, as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) in seconds.
  </Prop>

  <Prop name="jti" type="string" mode="output">
    A unique ID for the access token.
  </Prop>

  <Prop name="sub" type="string" mode="output">
    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.
  </Prop>
</Prop.List>

## Example response

```json
{
  "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"
}
```

## Error responses

### 400 Bad Request

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### client\_id body parameter has multiple values

```json
{
  "code": "invalid_field",
  "message": "client_id body param must have a single value"
}
```

##### client\_id body parameter is blank or empty

```json
{
  "code": "invalid_field",
  "message": "client_id body param must not be blank or empty"
}
```

##### client\_secret body parameter has multiple values

```json
{
  "code": "invalid_field",
  "message": "client_secret body param must have a single value"
}
```

##### client\_id basic auth parameter is blank or empty

```json
{
  "code": "invalid_field",
  "message": "client_id basic auth parameter must not be blank or empty"
}
```

##### secret basic auth parameter is blank or empty

```json
{
  "code": "invalid_field",
  "message": "secret basic auth parameter must not be blank or empty"
}
```

##### Request body too large

```json
{
  "code": "bad_request_body",
  "message": "Request body too large"
}
```

### 401 Unauthorized

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### Client secret is invalid (Unauthorized)

```json
{
  "code": "invalid_access_token",
  "message": "Client secret is invalid for {clientAppId}"
}
```

##### Access token is missing

```json
{
  "code": "invalid_access_token",
  "message": "Access token is missing"
}
```