Authentication

Every request uses HTTP Basic authentication.
The username is your tenant token and the password is a user token.

The encoded value is what HQ calls the encoded API token.
The integration user email and Copy to Clipboard under Encoded API Token on your profile give it to you ready to use.
To build it yourself, encode it locally and never paste tokens into online tools:

Most HTTP clients can also build the header from a username and password, for example curl -u TENANT_TOKEN:USER_TOKEN.

Where each token lives

Token	Where to find it	How it changes
Tenant token	The main Settings page: expand the Integrations box (not the Settings > Integrations page) and find Tenant API Token	Only HQ Support can reset it. Resetting it breaks every integration of the account.
User token	Settings > Users, open the user, User API Token	An administrator can click Generate new token (the old token stops working) or Delete.

A token is empty until it is generated: Generate new token creates a user token, and Copy to Clipboard on your profile creates any missing token for your account and your own user.
Both fields are visible only when your plan includes API access.

What the token can do

The API acts as the user behind the token.

Use a user with the administrator role, such as the integration user created from the Custom Integration Kit card.
With another user, reservation lists can leave out the reservations of branches or locations that user cannot access, without an error.

Disabled users cannot use the API.
Disable Integration User on the Custom Integration Kit card disables the integration user and stops its token.

Treat the encoded token like an administrator password: anyone who has it can read and change your account's data through the API.
Keep the token on your server.
Never call the API from a browser or a mobile app with it, because anyone could read it there.
Use one user per external system, so you can revoke one without affecting the others.

Authentication errors

Check the success field of every response: some authentication errors arrive with HTTP status 200.

HTTP status	`status_code` in body	Message	What to do
200	401	Invalid tenant token	Check the tenant token and that you are calling your own region.
200	401	Invalid user api token	Check the user token; it may have been regenerated or deleted.
401	401	Invalid user api token	The user is disabled. Use the token of an active user, or create the integration user again.
200	403	This user doesn't have access to this tenant	The user token belongs to a different HQ account.
402	402 or none	This account is suspended please contact your system administrator; or, in a body with only `message`, the deactivation reason, `Deactivated` or `Tenant in other region`	The account is suspended, deactivated or hosted in another region. Contact HQ Support.
3xx	-	-	A redirect to an HQ web address: the account moved to another region or was deactivated. Do not follow it; contact HQ Support.
401	401	Failed to authenticate because of bad credentials or an invalid authorization header.	The `Authorization` header is missing.
403	403	Often `Page not found`, even when the path is correct	The user's role does not allow this action.
500	500	You are not allowed to see this reservation	The user cannot access this reservation. Do not retry; use a user that can see it in HQ.

With HTTP 200 the message is in errors.error_message:

{
  "success": false,
  "status_code": 401,
  "errors": { "error_code": 401, "error_message": "Invalid tenant token" },
  "data": []
}

With a real HTTP error status the message is in message:

{
  "success": false,
  "message": "Invalid user api token",
  "status_code": 401,
  "data": []
}

Where each token lives#

What the token can do#

Authentication errors#

Where each token lives

What the token can do

Authentication errors