Skip to main content
Authentication is how HaulStow knows which business and developer application is making a request. You authenticate by sending an API key in the HTTP Authorization header.

​
Your first authenticated request

Every API request needs this header:
There is exactly one space between Bearer and the key. A complete curl example looks like this:
Live keys start with hsg_live_key_. Test keys start with hsg_test_key_. The complete value is a secret, just like a password.
Never place an API key in React, Vue, Angular, browser JavaScript, a mobile app, source control, screenshots, logs, analytics, or support messages. The public API intentionally has no CORS support because it is designed for backend-to-backend calls.

​
Where the key should live

Save the key in a server-side secret manager or environment variable. Your request flow should look like this:
Do not send the HaulStow key to your customer’s browser. If your frontend needs to create a delivery, it should call an endpoint on your backend, and your backend should make the HaulStow request.

​
Environments

The key and URL must belong to the same environment. There is no environment field in the request body.
  • Test key + sandbox URL: correct.
  • Live key + live URL: correct.
  • Test key + live URL: 401 ENVIRONMENT_MISMATCH.
  • Live key + sandbox URL: 401 ENVIRONMENT_MISMATCH.

​
Scopes

A scope is one permission attached to an API key. For example, a read-only dashboard may need deliveries:read but not deliveries:write. If the key is valid but lacks the needed scope, the API returns 403 INSUFFICIENT_SCOPE. Create or rotate a key with the correct scope in the developer portal; scopes cannot be added by sending them in an API request.

​
Key lifecycle

​
Creating a key

The developer portal shows a new key once. Copy it immediately into your secret manager. HaulStow cannot show the complete key again.

​
Rotating a key

Rotation creates a new key but leaves the old one working. This lets you update your server without downtime:
  1. Create the replacement key.
  2. Save it in your secret manager.
  3. Deploy your server with the replacement.
  4. Confirm requests are working.
  5. Revoke the old key.

​
Revoked or expired keys

  • A revoked key returns 401 API_KEY_REVOKED.
  • An expired key returns 401 API_KEY_EXPIRED.
  • A disabled developer application makes all its keys invalid.
Keep live and test credentials in separate configuration. Never substitute one automatically when the other fails.

​
If authentication fails

Check these in order:
  1. The header begins with Authorization: Bearer .
  2. You copied the complete key without extra spaces or quotation marks.
  3. The test/live key matches the sandbox/live URL.
  4. The key has the scope shown on the endpoint’s reference page.
  5. The key is not expired or revoked and the application is active.
See common errors for exact response codes.