Terminus Hub API Authentication

The Terminus Hub Public API authenticates every request with an API key sent in the Authorization header. There is no OAuth flow. Create a key once, store it securely, and send it with every call.

This page covers the Public API only. For browser session login and a side-by-side comparison of both methods, see Authentication.

Get an API key

An account owner or admin creates keys in the account menu: choose Settings, then API Keys. The key is shown only once, when it is created, so copy it straight into a secrets manager or environment variable. For creating, naming, and revoking keys, see API keys.

API keys are prefixed with thub_ to make them easy to identify in logs and configuration files. If a key does not start with thub_, it is not a valid Public API key.

Sending the Authorization Header

Include your API key on every request using the Authorization header with the Bearer scheme:

Authorization: Bearer thub_xxxxx

Replace thub_xxxxx with your actual API key. The header is required for all endpoints. There are no public, unauthenticated routes in the Public API.

Code Examples

The examples below show how to authenticate in three common environments. Replace thub_xxxxx with your API key.

curl https://api.terminus.app/api/v1/workspaces \
  -H "Authorization: Bearer thub_xxxxx" \
  -H "Content-Type: application/json"

const response = await fetch(
  "https://api.terminus.app/api/v1/workspaces",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer thub_xxxxx",
      "Content-Type": "application/json",
    },
  }
);

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

import requests

url = "https://api.terminus.app/api/v1/workspaces"
headers = {
    "Authorization": "Bearer thub_xxxxx",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

Authentication errors

Every authentication failure returns HTTP 401. What the body looks like depends on whether the header starts with Bearer thub_. When the header starts with Bearer thub_ but the key is not recognized (mistyped, truncated, or revoked), the body is the standard error object with type set to authentication_error, code set to unauthenticated, and message set to Invalid API key:

{
  "error": {
    "type": "authentication_error",
    "code": "unauthenticated",
    "message": "Invalid API key",
    "param": null,
    "path": null
  }
}

When the Authorization header is missing, or its value does not start with Bearer thub_ (for example, a different scheme or a key pasted without the Bearer prefix), the request is not treated as an API-key request at all. It is handled like a browser request with no signed-in session and still returns 401, but the body is not the standard error object shown above. Because the body differs between these two cases, branch on the HTTP status first. Treat any 401 as “fix the key or the header”, and don’t rely on error.code, which only the standard error object carries.

If you are receiving unexpected 401 responses, confirm the header starts with exactly Bearer thub_ (note the space), that the key is read from the correct environment variable, and that no extra characters (newlines, spaces) were included when it was stored.

Security Best Practices

Protecting your API key is critical, because anyone who holds it can make requests on your behalf.

Never expose your API key in client-side code. This includes browser JavaScript, mobile apps, or any code that ships to end users. Always make API calls from your server or a secure backend environment.

Use environment variables: store keys in environment variables (e.g., TERMINUS_API_KEY) and read them at runtime rather than hard-coding them in source files.
Use one key per integration: every key has the same read access to the whole account and there are no per-key scopes, so create a separate key for each integration. You can then revoke one without disrupting the others.
Rotate keys periodically: regularly cycle your API keys as a precaution, even if there is no known compromise.
Never commit keys to version control: add secrets files to .gitignore and audit your repository history if a key was accidentally committed.

Overview

Governance Models

Workspaces

Submissions

Records

Governance Models

Records

Submissions

Workspaces

Terminus Hub API Authentication

Get an API key

Sending the Authorization Header

Code Examples

Authentication errors

Security Best Practices

​Get an API key

​Sending the Authorization Header

​Code Examples

​Authentication errors

​Security Best Practices

Get an API key

Sending the Authorization Header

Code Examples

Authentication errors

Security Best Practices