API keys
Every request carries an API key in the Authorization header:
Authorization: Bearer hq_test_...
A key acts for the organization that owns it. A rate search with it prices that organization's contracts, and its quotes are that organization's quotes.
Environments
Each environment takes its own keys, and the start of a key says which environment it's for. A key sent to the wrong one is refused with api_key_wrong_environment, so test code can't reach live data by mistake.
| Environment | Address | Keys start with |
|---|---|---|
| Sandbox | https://api-dev.highqube.ai | hq_test_ |
| Production | Announced at launch | hq_live_ |
The sandbox has test data and may be reset. Don't keep anything there you need.
Creating a key
An admin of your organization creates keys in HighQube under Control Panel → API Keys. The key is shown once, at creation. HighQube keeps only a fingerprint of it, so a lost key can't be shown again: create a new one instead.
Keys belong to the organization, not to the person who made them, so an integration keeps working when that person leaves.
Permissions
Give each key only the permissions it needs. An endpoint called without the one it requires is refused with insufficient_scope, and required_scope in the error says which one is missing.
| Permission | Scope | Allows |
|---|---|---|
| Read rates & surcharges | rates:read | Search rates, price LCL and trucking, and look up locations and surcharges. |
| Read quotes | quotes:read | List quotes, open one in full, and download its workbook. |
| Create quotes | quotes:write | Turn a rate search into a quote to your customer. |
Expiry and rolling
- Expiry. By default a key lasts 180 days. An admin can choose 30, 90, 180 or 365 days instead. Admins are reminded 7 days and 1 day before a key expires.
- Rolling. Rolling a key creates its replacement and keeps the old key working for a grace period (24 hours by default). That gives you time to deploy the new key without downtime.
- Revoking. A revoked key stops working on its next request.
Roll keys on a schedule rather than waiting for them to expire, and roll straight away if a key may have leaked.
Restricting a key to your addresses
An admin can limit a key to your systems' IP addresses or ranges, such as 203.0.113.10 or 198.51.100.0/24. A call from anywhere else is refused with ip_not_allowed, so a leaked key is useless to anyone else. A key with no list works from any address.
The Test request button in this site's API reference sends requests through Scalar's servers, not your own. A key restricted to your addresses is refused there. Try requests with a sandbox key that has no address list.
Keeping keys safe
- Keep keys in a secret manager or environment variables. Never put them in source code, browser code or mobile apps.
- Use one key per system. Then revoking one doesn't stop the others, and usage shows which system made which calls.
- Restrict production keys to your servers' addresses.
- Check Control Panel → API Keys for keys that are unused or that failed calls.
