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

API keys are provisioned on a per-customer basis inside of the account by your Honestly admin.
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 — Request a fresh key from your Customer Success manager on a regular schedule to limit the impact of undetected exposure.
  • 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