Skip to main content
Every request to the Honestly Export API must be authenticated using an API key. You supply this key via the X-Api-Key HTTP request header — all endpoints require this header to be present and valid before they will return data. Requests made without a key, or with an invalid key, will be rejected with a 401 Unauthorized response.

​
Getting your API key

If you have the Admin role, you create API keys yourself inside the account: open API keys in your account settings, choose Create API key, and give the key a descriptive name. The key value is shown only once, right after you create it — copy it immediately and store it securely, because it cannot be retrieved later. From the same page you can also delete a key when an integration no longer needs it.
The API keys page requires the API Access (Business Intelligence) add-on. Without it, the menu item does not appear; email service@honestly.com to have access enabled.
Keep your API key secure. Do not share it with unauthorised parties, and never commit it to version control or include it in client-side code.

​
Key scopes

API keys carry scopes that decide which endpoints they can reach. Keys you create on the API keys page are read-only: they reach every GET endpoint in this reference, and are rejected with 403 if used to write. Keys issued before scopes existed keep exactly the read access they always had, so no existing integration changes. The key for Employee Import is the exception. It carries the employees:write scope, is issued separately when you connect the REST API integration on the Integrations page, and cannot read anything. Because it can change employee roles and data access, keep it in the system that owns your HR data and do not reuse it for reporting.

​
Using your API key

Once you have your key, include it as a header on every API request:
Here is a complete example using curl:
Replace YOUR_SECRET_API_KEY with the actual key you received. The same header must be included on every call, regardless of the endpoint you are targeting.

​
Security best practices

If you suspect your API key has been compromised, immediately revoke the existing key and issue a replacement within the account
Follow these practices to keep your integration secure:
  • Use environment variables — Store your API key in an environment variable or a secrets manager rather than hardcoding it in your source code.
  • Never commit keys to version control — Ensure .env files and configuration files containing keys are listed in your .gitignore.
  • Rotate keys periodically — On a regular schedule, create a fresh key on the API keys page, switch your integrations over to it, and then delete the old key there. This limits the impact of undetected exposure, and no Customer Success request is needed.
  • Restrict access — Only grant API key access to the systems and team members that genuinely require it. Avoid sharing a single key across multiple unrelated projects.

​
Authentication errors