Handling Exposed API Keys

If an API key has been exposed, or you suspect it has, act right away. You can regenerate the key or expire it. Which option is safe depends on the Tatum products you use with that key.

	Regenerate	Expire
Old key stops working	Immediately	Immediately
Notification subscriptions and webhook URLs	Kept	Permanently deleted
HMAC webhook secret	Kept	Permanently deleted
Virtual Accounts	Kept	Permanently deleted
Use when	You still need the key and its data	You no longer need the key

🛑
Using Notifications or Virtual Accounts? Regenerate the key, don't expire it. Expiring a key permanently deletes its Virtual Accounts, Notification subscriptions and HMAC webhook secret. This can't be undone.

📘
Using only RPC or Data API? These products don't store any data on the key. You can create a new key, switch your application to it, and expire the exposed one.

👤
Only the organization owner can regenerate or expire API keys. Team members can view and create keys, so they can prepare a temporary key, but the owner has to regenerate or expire the exposed one.

Regenerate an API Key

Regeneration replaces the key string and keeps everything attached to the key:

Notification subscriptions and their webhook URLs.
HMAC webhook secret. Webhooks sent after regeneration are signed with the same secret, so you don't need to enable HMAC again.
Virtual Accounts.

There are two ways to regenerate a key, depending on whether you prefer simplicity or no downtime.

🔐
Using KMS? KMS requires a 1:1 match with the API key that broadcasts transactions for signing. Update the key in your KMS setup as part of the rotation.

Option 1: Quick regeneration

Choose this option when a brief downtime is acceptable.

Log in to the Tatum Dashboard.
Go to the API Keys page.
Find the exposed API key.
Open the ⋮ menu.
Click Regenerate Key.
In the confirmation dialog, click Regenerate.
Copy the new key value and update it everywhere the key is used.

⚠️
The old key stops working immediately. Requests fail until you replace it with the regenerated key everywhere it's used.

Option 2: Regenerate without downtime

Choose this option to keep your integration running during the rotation. A temporary key handles requests while you regenerate the exposed one.

Log in to the Tatum Dashboard.
Go to the API Keys page.
Click Create API key to create a temporary key.
Update your application to use the temporary key.
Confirm that requests succeed with the temporary key.
Find the exposed key, open the ⋮ menu, and click Regenerate Key.
In the confirmation dialog, click Regenerate.
Update your application to use the regenerated key.
Confirm that requests succeed with the regenerated key.

⚠️
The temporary key starts empty. It has no HMAC secret, subscriptions or Virtual Accounts of its own, and anything created with it stays on it:

Webhooks for subscriptions created with the temporary key arrive without the x-payload-hash header unless you enable HMAC on that key too.

Subscriptions and Virtual Accounts created with the temporary key don't move to the regenerated key. Recreate or reconcile them on the regenerated key.

Expiring the temporary key later permanently deletes everything created with it.

If you can, avoid creating subscriptions or Virtual Accounts while the temporary key is active.

Expire an API Key

Expire an API key when you no longer need it and want it to stop working permanently.

Log in to the Tatum Dashboard.
Go to the API Keys page.
Find the exposed API key.
Open the ⋮ menu.
Click Expire.
In the confirmation dialog, type expire and click Expire.

Expired keys stay in the list when you turn on Show expired, but they can't be used or restored.

🛑
Expiring a key is permanent. All Virtual Accounts, Notification subscriptions and the HMAC webhook secret on the key are deleted. A new key starts with none of them: you need to enable HMAC on it and recreate your subscriptions.

After Rotation or Expiration

Update every application, environment variable, deployment setting and third-party integration that uses the affected key.
Remove the exposed key from source control, logs, tickets, chat messages and other shared locations.
If you use Notifications, check that webhooks still arrive and pass HMAC verification.
Review application activity for unexpected behavior.

Updated 19 days ago

Did this page help you?