Rotate an API key

Audience

Members and admins maintaining a workspace API key used by an automation.

API keys should be rotated at least annually, after any suspected exposure, or when the person who issued the key leaves. The procedure below avoids downtime by introducing the new key alongside the old one, then removing the old one.

The procedure

1. Issue a new key with the same scope

In BOS → Settings → API keys → + Create key. Match the scope of the key you're rotating; name it the same way + a year suffix (e.g. "Nightly stock sync (2026)" if you're rotating "Nightly stock sync (2025)"). Copy the plaintext to your secrets manager.

2. Deploy the new key alongside the old

In your automation's secrets manager / environment:

# Add the new key as a fallback for the old name
PLANA_KEY_NEW=pa_live_XYZ7AB2...

# Keep the existing
PLANA_KEY=pa_live_AB7K2XYZ1...

If the automation is in code, configure it to try the new key first and fall back to the old:

keys = [os.environ['PLANA_KEY_NEW'], os.environ['PLANA_KEY']]
for k in keys:
    try:
        resp = requests.get(url, headers={'Authorization': f'Bearer {k}'})
        resp.raise_for_status()
        break
    except requests.HTTPError as e:
        if e.response.status_code == 401:
            continue
        raise

This pattern means a single deploy gets the new key into rotation while the old one still works.

3. Verify the new key is in use

After the automation has run once or twice with the new key, check BOS → Settings → API keys. The new key's Last used column should update; the old key's should stop updating.

You can also check the Execution log — calls show the key prefix.

4. Remove the old key from the automation

Once you're confident the new key handles everything:

• Remove the old key from the automation's secrets manager
• Remove the fallback code if you added it
• Redeploy

5. Revoke the old key in BOS

Settings → API keys → click the old key → Revoke → confirm.

The old key stops working within seconds. If your automation still tries to use it (you forgot a place), the call returns 401 and you get an unambiguous signal of where the old key is still configured.

Why not just swap the key on a single deploy?

You can — for simple automations on a tight schedule (nightly job that runs once), a swap-then-deploy works fine. The two-key procedure is for:

• Automations that run continuously (workers, webhooks)
• Cases where a 1-second outage is unacceptable
• Multi-region or multi-instance deployments where rollout takes time

When to rotate sooner

• Suspected compromise — anything you see in the Execution log you didn't make
• An engineer left the company — rotate every key they had access to
• A laptop was lost or stolen — rotate every key potentially stored on it

In these cases, rotate before the new key is in place in the automation. Yes, the automation goes down for the rotation window; the trade-off is correct.

Tracking rotations

Decide a rotation cadence (annually is typical) and put a calendar reminder. A simple log of "key X rotated on date Y by person Z" is sufficient — keep it in your password manager next to the keys themselves.

What you cannot do

Want	Reality
Recover the old plaintext	No — only the bcrypt hash is stored
Re-enable a revoked key	No — issue a new one
See who else has access to the key	Only one user can have the plaintext (the one who issued it); secondary sharing happens outside BOS

Where to read more

• API keys — the settings view
• Execution log — verifying which key was used
• Platform → API keys — technical detail