Skip to the content

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"

Creating a key

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.

Roles

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 entry role a key sees only the lookups and batches of its own account; one of another account answers 404. 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 (402 with the code trial_ended). It can once the account that created it no longer has the administrator role. A key with the reviewer or admin role can receive owner_trial_ended when 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 entry role says so in its description.

GET /api/auth/me returns the account and the effective role behind a key (System).

Workspaces

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-Workspace with any other value is answered 403 with the code workspace_mismatch.
  • The role of a key there is the role it was given (entry acts as a member), capped at the role its creator holds in that workspace now, and never above admin. 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.
  • reviewer and admin see the lookups and batches of every member of the workspace, not of the whole service. Something of another workspace answers 404, 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 403 with the code workspace_required. A key whose creator's membership is suspended is answered 403 with member_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 admin and owner. Creating a webhook and changing its address need a person signed in to the application: a key is answered 403 with the code session_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).

Keeping a key safe

  • 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.