Authorization

Introduction

To use any of our API endpoints, you must provide an OAuth 2.0 access token as a bearer token in the header.

To generate an access token, you must first obtain your client credentials.

👍
Tip: Authorization for both the 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 Legacy (v1) and Results (v2) API endpoints.

Furthermore, you can use the same token on either endpoint version interchangeably, allowing you to combine legacy (v1) requests with the newer Results API (v2).

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.

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

How to generate an access token

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

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`

Request examples

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 axios, { AxiosResponse } from 'axios';

interface TokenResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
  scope: string;
}

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

const response: AxiosResponse<TokenResponse> = await axios.post(
  'https://auth.usertesting.com/oauth2/aus1p3vtd8vtm4Bxv0h8/v1/token',
  params,
  {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
  }
);

console.log(response.data.access_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)

❗️
Use a safe method to replace the CLIENT_ID and CLIENT_SECRET placeholders with the credentials you received.

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 the ACCESS_TOKEN value for use in your endpoint requests.

How to use an access token

The v1 endpoints use bearer token authorization.

Use the value of the access_token property from the 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 examples

curl --location 'https://api.use2.usertesting.com/usertesting/api/v1/workspaces' \
--header 'Authorization: Bearer ACCESS_TOKEN'

const ACCESS_TOKEN = process.env.ACCESS_TOKEN; // or replace with your token

const response = await fetch(
  'https://api.staging-use2.usertesting.com/usertesting/api/v1/workspaces',
  {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
    },
  }
);

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

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

const ACCESS_TOKEN = process.env.ACCESS_TOKEN as string;

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

interface Workspace {
  id: string;
  name: string;
  // add other fields as needed
}

const response = await fetch(
  'https://api.staging-use2.usertesting.com/usertesting/api/v1/workspaces',
  {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
    },
  }
);

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

const data: Workspace[] = 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 environment variable")

url = "https://api.staging-use2.usertesting.com/usertesting/api/v1/workspaces"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
}

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

if response.status_code != 200:
    raise RuntimeError(
        f"Request failed: {response.status_code} {response.text}"
    )

data = response.json()
print(data)

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