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 URL and versions

All requests go to https://api.dualentry.com, whether they come from your production organization or a sandbox organization provisioned for testing. A key only ever authenticates against the organization it was issued from, so sandbox and production integrations share the same host: nothing about the request changes except which key you send. Three mounts are served under this 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.

​
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 reads org_production_ for every customer-issued key, including keys for a sandbox organization. Sandbox and production organizations both run on the same infrastructure, so the prefix doesn’t distinguish them. Use the organization name shown in the API Keys table, not the key prefix, to tell which organization a key belongs to. 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 Developer access.

​
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 a separate key for a sandbox organization if you have one, so test traffic and production traffic are never authenticated by the same credential
  • 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 a key after any suspected exposure, or when its roles no longer match what the integration needs
  • 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 September 23, 2026