How to Authenticate Your Requests to the DualEntry API

This guide shows you how to get your first authenticated response from the DualEntry Public API and wire the credential into your application. You need an API key. If you do not have one, ask an Admin in your organization to issue you one from Settings → Organization → Developer access, telling them which operations your integration performs so they can scope it correctly. See How to Give an Integration Access to DualEntry for what that involves on their side.

Store the key outside your code

Put the key in an environment variable or your secret manager as soon as you receive it:

export DUALENTRY_API_KEY="your_api_key_here"

Do not commit it, log it, or ship it in client-side code. Anything that can read the key can act on your organization’s ledger with the roles the key carries. Those actions land in the audit trail attributed to the key rather than to a person. The key is shown once, at creation, and cannot be retrieved afterwards. If you lose the value you need a new key, so store it before you start experimenting. Name the variable for the environment it belongs to, not just for the product. DUALENTRY_API_KEY_PROD and DUALENTRY_API_KEY_DEV cost nothing extra and stop the two from being swapped in a config file later. The key’s own prefix records which environment issued it, so if you are ever unsure which one you are holding, compare it against the masked value in the API Keys table. See Authentication for the format.

Send it in the X-API-KEY header

Every request takes the key in the X-API-KEY header. Confirm the credential works with a single read before you build anything on top of it:

cURL
Python
JavaScript

curl https://api.dualentry.com/public/v1/invoices \
  -H "X-API-KEY: $DUALENTRY_API_KEY" \
  -H "Content-Type: application/json"

import os
import requests

response = requests.get(
    "https://api.dualentry.com/public/v1/invoices",
    headers={
        "X-API-KEY": os.environ["DUALENTRY_API_KEY"],
        "Content-Type": "application/json",
    },
)
print(response.status_code, response.json())

const response = await fetch('https://api.dualentry.com/public/v1/invoices', {
  headers: {
    'X-API-KEY': process.env.DUALENTRY_API_KEY,
    'Content-Type': 'application/json'
  }
});
console.log(response.status, await response.json());

A 200 and a JSON body means you are authenticated. The same key works against /public/v2/ for the current API version. /public/ with no version segment is the deprecated legacy mount and should not be used for new work. To run against development instead, swap the host for https://api-dev.dualentry.com and use a key issued from your sandbox organization in that environment. A production key does not authenticate there, because each environment holds its own organizations and keys. Keep the two keys in separately named variables so a revocation on one side never takes down the other.

If it does not authenticate

Authentication failures return 403, not 401, and a missing header and a bad key are not distinguished by status code. Read the error message to tell them apart. API key authentication failed means the header did not arrive, arrived empty, or carried a key that is unknown or revoked:

{
  "success": false,
  "errors": {
    "__all__": ["API key authentication failed"]
  }
}

Print the outgoing request and check that your HTTP client, proxy, or gateway is not stripping custom headers, and that you are not sending Authorization instead. If the header is definitely arriving, ask your Admin to confirm the key’s status reads Active in the API Keys table. If it reads Revoked, you need a new key. Access denied means the opposite: the key authenticated, but its roles do not cover the operation.

{
  "success": false,
  "errors": {
    "__all__": ["Access denied"]
  }
}

A key created with no roles at all fails this way on every endpoint. Ask your Admin to edit the key’s roles from the ⋮ menu on its row. The secret survives the change, so you do not need a new key or a redeploy. For status codes, headers, and the full error format, see Authentication.

Developer Guide

V2 (latest)

V1

Release Notes & Changelog

How to Authenticate Your Requests to the DualEntry API

Store the key outside your code

Send it in the X-API-KEY header

If it does not authenticate

Next steps

​Store the key outside your code

​Send it in the X-API-KEY header

​If it does not authenticate

​Next steps

Store the key outside your code

Send it in the X-API-KEY header

If it does not authenticate

Next steps