Skip to content
DevelopersGet an API key

Authentication

Every request carries an API key. The key decides which workspace you read, and nothing you send can change that.

Sending the key

Put the key in the Authorization header as a Bearer token:

HTTP
GET /v1/loads HTTP/1.1
Host: api.goharlo.com
Authorization: Bearer hk_…

If a tool can only set a custom header, X-Api-Key: hk_… works too. Keys in the URL are not accepted: URLs end up in logs, browser history and spreadsheets.

Who can make keys

Workspace owners and admins, in Settings, API keys. A workspace can have up to 25 active keys. When you create one you choose when it expires: 30 days, 90 days, a year, or never.

Access levels

You choose one when you make the key:

Read onlyEvery GET endpoint. Can't change anything in Harlo.
Read and record paymentsAlso POST /v1/payments, so an accounting tool can mark Harlo invoices paid. Its scopes are read and payments:write.

/v1/me shows a key's scopes. A read-only key that tries to write gets 403 insufficient_scope.

What a key can see

  • All of the workspace's loads, billing, customers, fleet, carriers, facilities, documents and activity.
  • Never another workspace's data. If you belong to several workspaces, make a key in each.
  • Never identity, medical, drug-test, background-check or bank documents, and never a driver's birthday or login details, even though they may be in Harlo.
  • Nothing it can change, unless it may record payments. Payments follow the same rules as in Harlo, and the activity log names the key that recorded each one.

Keeping keys safe

  • Harlo stores only a fingerprint (a SHA-256 hash) of each key. If you lose one, revoke it and make a new one; it can't be shown again.
  • Use one key per tool, so you can revoke one without breaking the others.
  • Call the API from a server or an automation tool, not from a web page: anything in a browser can be read by whoever opens it.
  • Settings, API keys shows when and from where each key was last used, and the last 25 requests. Revoking takes effect on the next request.

If a key leaks

Revoke it in Settings, API keys straight away, then make a new one for the tool that used it. Requests with a revoked key get 401 api_key_revoked.
NextPagination and syncing