Skip to main content
All API requests must include an API key in the X-API-KEY header.

​
How it works

  1. An Admin generates an API key from the DualEntry dashboard and assigns it one or more roles
  2. Include the API key in the X-API-KEY header with every request
  3. The API validates the key, binds the request to that key’s organization, and authorizes each endpoint against the key’s roles
Requests are authorized in two stages, which is why there are two distinct failure messages. The key is either valid or it is not, and a valid key either carries the roles an endpoint requires or it does not. The key also identifies the organization, so requests carry no separate tenant or organization parameter. A key can never read data belonging to another organization. Nothing else is required to identify yourself. There is no token exchange, no refresh step, and no session to maintain, so the same header works on the first request and the millionth. A request to the invoices collection looks like this:

​
Base URLs and versions

A key authenticates only against the environment it was created in. Production keys do not work against development, and the reverse is also true. Three mounts are served under each host: The same key works against every mount. Choosing a version is a URL decision, not a credential one, so moving an integration from V1 to V2 needs no new key and no change to the header. The environment is also recorded in the key itself, in the prefix described below, which is the quickest way to confirm that a config file is pointing a production key at production.

​
Getting an API key

An Admin in your organization issues keys from Settings → Organization → Developer access → API Keys. Only the Admin role can reach that tab. See How to Give an Integration Access to DualEntry for the procedure, or send that page to whoever holds the role. A key carries its own roles, assigned when it is created. It is not tied to the user who created it and does not inherit that user’s permissions or entity scoping, and it reaches every company in the organization. An Admin can change a key’s roles later without invalidating the secret, so a key that turns out to be too narrow does not require a redeploy. Once you receive your key, store it securely in your application. The key is shown only once at creation time and cannot be retrieved later.
Security: Never expose API keys in client-side code, public repositories, or logs. Use environment variables or secure secret management services.

​
Key format and statuses

After creation, a key is only ever shown masked: the prefix, four asterisks, and the last four characters of the secret.
The prefix is org_{environment}_{4 hex characters}, where environment is one of production, dev, test, or local. That segment is the reliable way to tell which environment a key belongs to when two are side by side in a config file. A key holds one of two statuses: Revocation is immediate and one-way. A revoked key cannot be reactivated, and its name stays reserved, so a replacement needs a different one. Keys do not expire on their own; an Active key stays valid until someone revokes it. For the columns shown in the API Keys table, see Organization settings.

​
Authentication errors

Both failure modes return 403. The status code does not distinguish them; the error message does. Error response:
A key created with no roles authenticates successfully and then returns Access denied on every permission-guarded endpoint. A revoked key is indistinguishable from an unknown one in the response; both read API key authentication failed. Requests refused for exceeding a quota return 429 instead, which is covered in Rate limiting.

​
Best practices

  • Store API keys in environment variables or secret management services
  • Use separate API keys for development and production environments. A key only authenticates against the environment it was created in
  • Issue one key per integration, so revoking one never takes down another
  • Assign the narrowest roles the integration needs. A key holding Admin bypasses permission checks entirely, and nothing in the key table records what it was meant to do
  • Rotate keys regularly for enhanced security
  • Never commit API keys to version control
Check the Last Used column periodically and revoke any key whose integration has been retired; a key stays valid until someone revokes it, with no expiry. Actions taken with a key appear in the audit trail attributed to API Key rather than to a person, so a key shared between systems produces a history nobody can untangle after the fact. One key per integration is what keeps that record readable.

​
Next steps

Last modified on August 17, 2026