Skip to main content
This guide shows you how to swap out a DualEntry API key. Use it when a key has been lost, when it may have been exposed, or when it is due for rotation. A key cannot be recovered or re-shown after creation, and a revoked key cannot be reactivated. Replacement is the only remedy in every case. What changes is the order of the steps. You need the Admin role to create and revoke keys, and access to wherever the key is stored to complete the cutover. Note that a key’s roles can be edited in place. If the only thing wrong is that the key is over- or under-scoped, use Edit on its row instead of replacing it.

​
Choose your order

If the key may have been exposed publicly, in a commit, a log, a screenshot, or a support thread, revoke first and accept the outage. Every minute the key stays active is a minute someone else can post to your ledger. A key carries the roles it was given rather than the permissions of whoever finds it, so the blast radius is whatever you scoped it to on the day you issued it. Otherwise, for a lost key or a scheduled rotation, cut over first and revoke last. There is no downtime, because two keys for the same integration can be live at once. Nothing in DualEntry limits how many keys an organization holds or ties them to a single consumer. If you are unsure which case you are in, treat it as exposure. Reissuing costs one deploy; an active key in a public repository costs whatever an attacker can do with its roles before someone notices.

​
Cut over first (lost key or routine rotation)

1

Issue the replacement

Go to Settings → Organization → Developer access → API Keys and create a new key with the same roles as the old one. Names must be unique, so give it a name that distinguishes the two, then copy the key from the dialog. See How to Give an Integration Access to DualEntry for the full sequence.
2

Update the secret

Replace the value in your environment variables, secret manager, and CI configuration, then deploy or restart so the running process picks it up.
3

Confirm traffic has moved

Check the Last Used column on both rows. The new key should show today’s date. The column is date-only and updates lazily, so it will not tell you the old key went quiet an hour ago, only that it has not been used since some earlier day. If you need certainty on the same day, wait until the following day and confirm the old key’s date has stopped advancing before you revoke. Otherwise revoke knowing that a straggler will fail loudly rather than silently.
4

Revoke the old key

Select the ⋮ menu on the old key’s row and choose Revoke API Key. It takes effect at once, with no confirmation prompt.

​
Revoke first (suspected exposure)

1

Revoke immediately

On the exposed key’s row, select the ⋮ menu and choose Revoke API Key. There is no confirmation step. Calls using it start failing with 403 and API key authentication failed at once.
2

Issue a replacement and cut over

Create a new key with the same roles, update the secret, and redeploy. The integration is down until this completes.
3

Clean up the exposure

Purge the key from wherever it leaked. Rewriting a commit is not enough on its own if the repository was pushed or forked, which is why the revocation comes first.
4

Check what was done with it

Review the audit trail and look for entries whose actor reads API Key. Those are the actions taken through the Public API while the key was live. The audit trail does not name which key acted, so if several keys were active you will need to reason from the records themselves, and from the create, update, and revoke entries recorded against the keys.

​
If something goes wrong

Calls fail after the cutover with API key authentication failed. Something is still holding the old value, or the new one was copied with surrounding whitespace. Check that the deploy actually restarted the process, then print the first characters of the variable your client reads and confirm it matches the new key’s prefix in the API Keys table. Calls fail after the cutover with Access denied. The replacement authenticated but was created with different roles from the original. Compare the Roles column on the two rows and use Edit on the new key to match; you do not need to reissue. You revoked the wrong key. Revocation is one-way and there is no undo. Create a replacement with the same roles and cut the affected integration over to it. The old key’s Last Used date keeps advancing. Another consumer is still on the old value. Check other environments, scheduled jobs, CI configuration, and local developer machines before you revoke, since revoking will take all of them down at once.

​
Keep replacement cheap

Rotation hurts in proportion to how many systems share a key. If this replacement was painful, issue one key per integration next time so the next rotation touches one config file instead of several. The same goes for scope. A key that holds Admin because it was quicker than picking roles turns every future rotation into a security review, because nobody can tell from the key table what it was actually used for. A narrowly scoped key is one you can revoke without a meeting. Naming helps as much as scoping. billing-service-prod tells the next person which system breaks if they revoke it; api-key-2 tells them nothing, so the safe move becomes leaving it alone. Since names are unique per organization and revoked keys keep theirs, a convention that includes the consumer and the environment survives several rotations without collisions. Finally, write down where the key is stored at the moment you hand it over. Most of the time spent on an urgent rotation goes into finding every config that holds the old value, not into clicking Revoke.

​
Next steps

Last modified on August 17, 2026