Authentication
API keys for the HTS Pilot API - where to create one, how to send it, what a role allows, and what 401 and 403 answers look like.
Every request but GET /api/health needs an API key, sent in the X-API-Key header:
curl https://htspilot.com/api/usage/me \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
An administrator creates keys in the application, under Admin, API keys: give the key a name and a role. The key
is shown once, when it is created; only its first characters are kept for display afterwards. A key starts with
hts_. It can be revoked at any time on the same page, and a revoked key answers 401 from then on.
A key belongs to the workspace it was created in (Workspaces). The list of keys in the application shows, next to the role a key was given, the role it acts with in that workspace now, or none when it acts nowhere.
Keys are not created through this API: the key management routes belong to the application and are not part of the customer API.
A key has one of three roles, and acts for the account that created it:
| Role | May |
|---|---|
entry (shown as "user") |
Create and read its own lookups and batches, use the catalog, read tariff data and usage |
reviewer |
Everything above for all lookups and batches, plus decisions, deleting a SKU, acknowledging an alert, reports |
admin |
Everything above, plus webhooks |
- The role of a key never exceeds the role of the account that created it. If the account is later given a lower role, the key is cut to that role too.
- With the
entryrole a key sees only the lookups and batches of its own account; one of another account answers404. Reviewers and admins see all of them. - The plan of the account that created the key applies to the key (Rate limits and quotas).
- So does its free trial, when it has one. Only an administrator creates a key, and an administrator account is
not on a trial, so a key does not normally receive the refusal of a read-only account (
402with the codetrial_ended). It can once the account that created it no longer has the administrator role. A key with therevieweroradminrole can receiveowner_trial_endedwhen it starts work on a batch of another account whose trial has ended (Errors). While workspaces are switched on, the plan and the trial are those of the workspace instead (Workspaces). - An operation that needs more than the
entryrole says so in its description.
GET /api/auth/me returns the account and the effective role behind a key (System).
A workspace holds the lookups, batches, catalog, keys, webhooks, credits and plan of the people who work in it:
the account of one person (its personal workspace), or a team that several accounts share. Each member has a role
there: owner, admin, reviewer or member. The rules of this section apply while the service has workspaces
switched on; until then a key acts with the roles above, for its account.
- A key acts in the workspace it was created in, and nowhere else. It does not need to name it. A request made
with a key that sends the header
X-HTS-Workspacewith any other value is answered403with the codeworkspace_mismatch. - The role of a key there is the role it was given (
entryacts as amember), capped at the role its creator holds in that workspace now, and never aboveadmin. If the creator is given a lower role, the key acts with that role from the next request. The role of the creator's account on the service plays no part. reviewerandadminsee the lookups and batches of every member of the workspace, not of the whole service. Something of another workspace answers404, as if it did not exist.- The plan, the free trial and the credits that count are the workspace's (Usage).
- A key whose creator is no longer an active member of the workspace, or whose workspace was closed or suspended,
acts nowhere: it is answered
403with the codeworkspace_required. A key whose creator's membership is suspended is answered403withmember_suspended(Errors). A membership is suspended when a team has more members than its plan has seats (owners are never suspended); an owner or admin of the team reactivates it in the application. Meanwhile the person can be given read-only access for 1, 7 or 30 days there, but a key of that person stays refused. - Keys and webhooks are managed by the workspace's
adminandowner. Creating a webhook and changing its address need a person signed in to the application: a key is answered403with the codesession_required(Webhooks).
GET /api/auth/me names the workspace a key acts in and its role there, in workspace and workspace_role.
The web application signs in with a session token sent as Authorization: Bearer <token>. Those sign-in and
account routes are not part of the customer API and are not described here. Integrations use an API key.
No key: 401.
{ "detail": "Please sign in", "code": "unauthenticated" }
A key that does not exist or was revoked: 401. A key whose owner account was deactivated also answers 401, with
the message "The API key owner has been disabled".
{ "detail": "Invalid API key", "code": "unauthenticated" }
A valid key whose role does not allow the call: 403.
{ "detail": "Admin role or higher required", "code": "forbidden" }
A valid key whose plan does not include the feature, or would exceed a plan limit: 403, with details
(Errors).
- A key is a secret with the rights of its role. Keep it in a secret store or an environment variable, never in source code, a URL, a log line or a browser page.
- Call the API from your servers. A key in front-end code is readable by everyone who opens the page.
- Give each integration its own key with the lowest role that works, so one can be revoked without stopping the others.
- If a key may have leaked, revoke it and create a new one. There is no way to read a key again after it was created.
- The API explorer keeps the key you type in memory for that tab only; it is gone when the page is reloaded.