Authorization

Introduction

To use any of our API endpoints—Legacy endpoints (v1) and Results API (v2)—you must provide an access token in the header as a bearer token.

This section explains how to generate and then use an access token.

General workflow:

Prerequisites
1. Get added as a team member within the account workspaces where you want to use the API.
2. Obtain your client credentials (this is step is done only once per API user).
Generate an access token
1. With the client credentials, make an API token request to generate an access token.
2. The access token expires after an hour, so you'll have to generate a new afterwards.
Use the access token
1. In every API request you make, use the Authorization Bearer header scheme with the access token you generated.
2. Remember, after an hour, you will need to generate a new access token.

👍
Tip: Authorization for both Legacy (v1) and Results (v2) API is obtained through the same process.
This means that:

You can use your client credentials to generate tokens for both the Legacy (v1) and Results (v2) API.

Furthermore, you can use the same token interchangeably on either Legacy (v1) or Results (v2) API endpoints.

Prerequisites

Ensure that your email address has been added as a team member to the workspaces you intend to query data from. Contact an account admin for assistance.
Contact [email protected] to register your email address for API use and request your client credentials. The support team will then send you your credentials (client ID and client secret) through a secure channel, for example, a 1Password link.

👍
Remember: You will only have access to the data within the workspaces where the email used to register you as a team member is also the email address used to obtain your client credentials.

❗️
Do not share your client credentials and keep them in a safe place.

How to generate an access token

📘
Note: Access tokens expire after 3600 seconds (1 hour). A new access token must be generated after the expiration time to make further requests.

After obtaining your client credentials, use the following endpoint to generate an access token:

Method & URL

POST https://auth.usertesting.com/oauth2/aus1p3vtd8vtm4Bxv0h8/v1/token

Header

Header	Value
Content-Type	application/x-www-form-urlencoded

Request body

URL-encoded form

Key	Value
client_id	CLIENT_ID
client_secret	CLIENT_SECRET
grant_type	client_credentials
scope	studies:read

Replace CLIENT_ID and CLIENT_SECRET placeholders with the values obtained from the UserTesting support team.

Request example

curl --location --request POST 'https://auth.usertesting.com/oauth2/aus1p3vtd8vtm4Bxv0h8/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'scope=studies:read'

const params = new URLSearchParams({
  client_id: process.env.CLIENT_ID,
  client_secret: process.env.CLIENT_SECRET,
  grant_type: 'client_credentials',
  scope: 'studies:read',
});

const response = await fetch(
  'https://auth.usertesting.com/oauth2/aus1p3vtd8vtm4Bxv0h8/v1/token',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: params.toString(),
  }
);

if (!response.ok) {
  throw new Error(`Token request failed: ${response.status}`);
}

const token = await response.json();
console.log(token);

import os
import requests

url = "https://auth.usertesting.com/oauth2/aus1p3vtd8vtm4Bxv0h8/v1/token"

data = {
    "client_id": os.getenv("CLIENT_ID"),
    "client_secret": os.getenv("CLIENT_SECRET"),
    "grant_type": "client_credentials",
    "scope": "studies:read",
}

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

response = requests.post(url, data=data, headers=headers)
response.raise_for_status()

token = response.json()
print(token)

Response sample

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "ACCESS_TOKEN",
    "scope": "studies:read"
}

In the response sample, the ACCESS_TOKEN placeholder represents a JSON Web Token (JWT).

❗️
Do not share the token and use a safe method to store the value of the access_token property for use in your endpoint requests.

How to use an access token

Use the value of the access_token property from the generate token response in the header of all the endpoint requests you make.

For all API requests, add the following header:

Header	Value
Authorization	Bearer ACCESS_TOKEN

Request example

curl --location 'https://api.use2.usertesting.com/api/v2/sessionResults/?testId=TEST_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN'

const ACCESS_TOKEN = process.env.ACCESS_TOKEN;

if (!ACCESS_TOKEN) {
  throw new Error('Missing ACCESS_TOKEN');
}

const url =
  'https://api.use2.usertesting.com/api/v2/sessionResults/' +
  '?testId=82629d39-c9b5-4acc-8edc-0f2e34c0b07c&rowsPerPage=10&pageNumber=21';

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

import os
import requests

ACCESS_TOKEN = os.getenv("ACCESS_TOKEN")

if not ACCESS_TOKEN:
    raise RuntimeError("Missing ACCESS_TOKEN")

url = (
    "https://api.use2.usertesting.com/api/v2/sessionResults/"
    "?testId=82629d39-c9b5-4acc-8edc-0f2e34c0b07c"
    "&rowsPerPage=10"
    "&pageNumber=21"
)

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {ACCESS_TOKEN}",
}

response = requests.get(url, headers=headers)
response.raise_for_status()

data = response.json()
print(data)

❗️
Use a safe method to replace the ACCESS_TOKEN placeholder with the access token you received in the generate token response.

📘
To get the TEST_ID for the request example above, refer to How to Obtain a Test ID (UUID).