Authentication

The REST API uses Bearer token authentication. You include your API key in the Authorization header of every request to identify your application and authorize access to resources.

Obtaining an API key

Generate an API key from the Thought Industries admin panel under Settings → API Keys. Each key is scoped to a single instance and carries the permissions of the role you assign during creation.

Treat API keys as secrets. Never commit them to version control or expose them in client-side code.

Making authenticated requests

Include the API key in the Authorization header using the Bearer scheme:

curl -X GET "https://api.thoughtindustries.com/incoming/v2/users" \
  -H "Authorization: Bearer ti_live_a1b2c3d4e5f6g7h8i9j0"

const response = await fetch("https://api.thoughtindustries.com/incoming/v2/users", {
  headers: {
    "Authorization": "Bearer ti_live_a1b2c3d4e5f6g7h8i9j0",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.thoughtindustries.com/incoming/v2/users",
    headers={"Authorization": "Bearer ti_live_a1b2c3d4e5f6g7h8i9j0"}
)

data = response.json()

$ch = curl_init("https://api.thoughtindustries.com/incoming/v2/users");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer ti_live_a1b2c3d4e5f6g7h8i9j0",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

Token types

Token prefix	Environment	Use case
`ti_live_`	Production	Live data access
`ti_test_`	Sandbox	Development and testing

Use sandbox tokens during development to avoid modifying production data.

OAuth 2.0 (Enterprise)

Enterprise customers can authenticate with OAuth 2.0 for granular access control and token lifecycle management.

Grant type	Use case
`client_credentials`	Server-to-server integration (no user context)
`authorization_code`	User-facing apps that act on behalf of learners

Contact your account team to enable OAuth 2.0 for your instance.

Error responses

When authentication fails, the API returns a 401 Unauthorized response:

Response: 401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired API key."
}

Common causes of authentication errors:

Missing Authorization header
Malformed token (incorrect prefix or length)
Revoked or expired API key
Key does not have permission for the requested resource

Security best practices

Rotate API keys on a regular schedule (at minimum every 90 days)
Use environment variables to store keys in your deployment pipeline
Assign the minimum required role to each key
Monitor API key usage in the admin panel audit log
Revoke keys immediately if you suspect compromise

Rate limits — request quotas and throttling behavior
Status codes — HTTP response code reference