Authentication

All API requests use Bearer token authentication.

Token Types

Type	Prefix	Tied to	Use case
Personal Access Token (PAT)	`ul_pat_…`	Your user account	Recommended for development, testing, scripts, and integrations

PATs inherit the permissions of the role assigned when the token is created. Personal Access Tokens are the recommended authentication method for the Unleash Live API.

Step 1 — Create a Token

Via the UI

Before you create a PAT, make sure you are signed in to your Unleash Live account and that Developer mode is enabled on your profile.

Go to Your Profile → Developers.
In the Personal Access Tokens (PAT) section, click Create Token.
Enter a descriptive token name.
Select the appropriate role:
- Viewer for read-only access
- Contributor for create and update access
- Admin for full administrative access
Choose an expiration period: 7 days, 30 days, 60 days, 90 days, or 1 year.
Click Create.
Copy the token immediately and store it securely. The full token value is shown only once.

Use the principle of least privilege and choose the lowest role and shortest expiry that still works for your integration.

Step 2 — Use the Token

Use your PAT as a Bearer token in the Authorization header:

curl https://api.unleashlive.com/v1/analytics/version \
  -H 'Authorization: Bearer <YOUR_PAT>'

const response = await fetch('https://api.unleashlive.com/v1/analytics/version', {
  headers: {
    Authorization: `Bearer ${process.env.UL_API_TOKEN}`,
  },
});
const data = await response.json();

import os, httpx

headers = {"Authorization": f"Bearer {os.environ['UL_API_TOKEN']}"}
response = httpx.get(
    "https://api.unleashlive.com/v1/analytics/version",
    headers=headers,
)
print(response.json())

Base URL

Use the public API base URL:

https://api.unleashlive.com

Token Lifecycle

PAT default expiry: 30 days
Revoke a token any time via Your Profile → Developers

Legacy: Cognito JWT

Cognito Helpers

The cognito.js module provides helper functions for:

Initialising the AWS SDK client with identity pool credentials
Creating a Cognito user pool and user instances
Decoding JWT tokens
Building authentication details

The actions.js module uses the Cognito helpers to authenticate a user. On success it returns the access token, ID token, refresh token, and custom claims (identityId, companyId, teamId).

An example sign-in script can be run from any of the sample entry points, such as media-drive and flights.

Required Headers

Every GraphQL request must include the header authorization with the ID token. Every REST request must include the header X-Amz-Cognito-Security-Token with the security token.

Quick Hint

If you are using another programming language, you can use the following command in your terminal to generate a security token:

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --region ap-southeast-2 --client-id 7jhe1lfkb5pvhbkicc3d14m0ej --auth-parameters USERNAME=<USER_LOGIN_EMAIL>,PASSWORD=<PASSWORD>

Legacy: API Key

This authentication method is mainly used to fetch analytics data generated during your AI sessions. Please contact here or your Account Manager to sort out API keys for you. Further, you can also email us at support@unleashlive.com.