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.

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

Sessions are not for integrations

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.

What 401 and 403 look like

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.