Skip to main content
An API key is a secret bearer token that lets a script, integration, or service call the Terminus Hub API as your account, without a personal login. Account owners and admins create and revoke keys in the account menu under Settings, then API Keys. A key is shown only once, when it is created. API access is included on every plan.
Use an API key when you want to read Terminus Hub data programmatically: records, submissions, workspaces, and governance models. Keys are read-only, so an integration cannot create submissions or change data with one. To create submissions from an AI app such as Claude or ChatGPT, connect the app instead. Each request carries the key, and Terminus Hub checks it against your account’s keys on every call. For the full request format and error responses, see API authentication.

​
What a key looks like

Every key starts with the prefix thub_ followed by random characters:
The thub_ prefix makes Terminus Hub keys easy to recognize in code, logs, and secret scanners, so an accidental leak can be flagged automatically.

​
How a key authenticates a request

Send the key in the Authorization header as a bearer token on every API request:
For example, listing records:
A request with no Authorization header, or with a key that has been revoked or is otherwise invalid, gets a 401 authentication error. Terminus Hub records the time of each successful authentication as the key’s last-used timestamp, so you can tell which keys are active. Cookie-based session auth is what the Terminus Hub web app uses for people signed in through a browser. Integrations use an API key instead. See API authentication for both schemes side by side.

​
How keys are scoped

A key is scoped to a single account, and to that account only. There are no per-key scopes, roles, or permissions, and no expiry date. Every key is read-only and can read everything the API exposes for its account.
Because the only boundary is the account, a key cannot read or change another account’s data. Two practical limits follow from this design:
  • The same access for every key. Every key can read the full API surface available to its account. You cannot limit one key to some resources.
  • No expiry. A key stays valid until it is revoked. To rotate, create a new key, switch your integration over to it, then revoke the old one.
Keys can reach only the Public API: listing and reading governance models, workspaces, and records, and listing submissions. A request to any other endpoint, including creating a submission or account administration (members, billing, the keys themselves), is refused with a 403 error. See API authentication for the resources a key can call.

​
Create a key

1

Open API Keys

In the account menu, choose Settings, then API Keys. The list shows each key’s Name, when it was Created, and when it was Last used (or Never).
2

Create the key

Click Create key, give it a Name that says where it will be used (for example CI pipeline), and click Create.
3

Copy it now

The API key created dialog shows the full key once. Click the copy button and store the key in a secrets manager or environment variable before you click Done. It cannot be shown again, because Terminus Hub stores only a one-way hash of it.

​
Revoke a key

On the API Keys page, click the revoke button on the key’s row and confirm with Revoke. Revoking takes effect immediately: any integration still using the key starts getting 401 errors, and the key cannot be restored. There is no pause or disable switch. Only account owners and admins can create and revoke keys. If you need a key and are not an owner or admin, ask one to create it for you.

​
Keeping a key safe

A key carries account-level access, so treat it like a password.

Store it outside source code

Keep keys in environment variables or a secrets manager, never hardcoded in code or committed to a repository.

Rotate by replacing

To rotate, create a new key, deploy it everywhere, then revoke the old one. Do this after offboarding someone or if you suspect a leak.

One key per integration

Give each integration or environment its own key, so the Last used date tells you which one is active and you can revoke one without breaking the rest.

Revoke on exposure

If a key may have leaked, revoke it right away and issue a replacement. Revoking takes effect immediately.

​
Gotchas

  • Shown once. The raw key appears only at creation. If you lose it, you cannot recover it; revoke that key and make a new one.
  • No scopes, no expiry. Every key has the same account-wide reach and never expires on its own. Control access by limiting who holds keys and revoking unused ones.
  • Revoking is permanent. There is no pause or disable, and a revoked key cannot be restored.

API authentication

The bearer-token header, session auth, and error responses in detail.

API overview

What the Terminus Hub API offers and how requests are shaped.

Pagination and errors

Response envelopes, paging, and the structured error format.

Team members

Who can manage the account, including creating keys.