Skip to main content
The Terminus Hub Public API uses API key authentication exclusively. There is no OAuth flow or session-based login for the Public API. Every request is authenticated by passing your API key in the Authorization request header. This makes integration straightforward: generate a key once, store it securely, and include 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.

​
Creating an API Key

API keys are managed from your Terminus Hub account settings. Navigate to Account → API Keys to generate a new key. Each key is shown only once at creation time. Copy it immediately and store it in a secure location such as a secrets manager or environment variable.
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://hub.terminus.app/api/v1/workspaces \
  -H "Authorization: Bearer thub_xxxxx" \
  -H "Content-Type: application/json"

​
Authentication errors

When authentication fails, the API responds with HTTP 401 and an error object whose type is authentication_error. For a missing, malformed, or unrecognized key, code is null and message is Invalid API key. 
{
  "error": {
    "type": "authentication_error",
    "code": null,
    "message": "Invalid API key",
    "param": null,
    "path": null
  }
}

​
What causes an authentication error

A 401 authentication_error is returned whenever the key isn’t recognized, most often because the key is missing, was mistyped or truncated, has been revoked, or doesn’t begin with Bearer thub_. Authentication failures don’t carry a finer-grained code (it is null), so branch on the HTTP status and error.type rather than on a code.
If you are receiving unexpected authentication_error 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 carries the same full account access, 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.