Rotating an API key

Cash Runway API keys (the modern crun_* family — both USER keys at Settings → API keys and PARTNER keys at Partner → API keys) have no dedicated "rotate" button. Rotation is a three-step pattern using the existing create and revoke actions:

1. Create a new key.
2. Deploy it into the consumer (script, integration, agent, MCP client) and confirm it works.
3. Revoke the old key.

Both keys are independently valid in between, so there's no downtime window — the swap is observably zero-downtime even for high-frequency callers.

This page is the operator runbook for that workflow. For the broader "what is an API key, what scopes mean, who can issue them" treatment, see API keys.

Why rotate

Three common triggers:

• Scheduled hygiene. Long-lived bearer tokens accumulate exposure surface (logs, shell history, leaked screenshots, CI artefacts, old laptops). Many organisations rotate quarterly or six-monthly even without a known incident.
• Personnel change. A team member with access to the key has left, or has changed role and no longer needs the scopes the key carries.
• Leak response. A key has been (or might have been) committed to a public repo, posted in a chat channel, or otherwise exposed. See Leak response below — the order of operations matters when there's an active threat.

The audit log surfaces Last used for every key, which is the easiest way to find abandoned-but-still-active keys that should be rotated or revoked outright.

The 3-step pattern

1. Create the new key

1. Open Settings → API keys (USER key) or Partner → API keys (PARTNER key).
2. Click Create API key.
3. Give it a label — a label that identifies what it replaces makes audit-log review easier. For example:

   MCP server (rotated 2026-05-26, replaces "MCP server" issued 2025-11-20)

4. For PARTNER keys, tick the same scope set the old key carried (USER keys inherit the issuing user's live Membership scope, so there's no per-key scope picker).
5. Click Create key. The full secret is shown once — copy it into your password manager or your tooling's secret store immediately.

2. Deploy the new key

Update the consumer to use the new key:

• MCP server / CLI. Update the CASHRUNWAY_API_KEY environment variable (or whatever your wrapper uses) and restart the process.
• CI / scheduled jobs. Update the secret in your CI provider's secret store; the next run picks it up.
• Third-party integration / agent. Paste the new key into the integration's settings panel.

Then verify the new key works — make at least one real call (a /status ping, a /cash-position read, a single MCP query) and confirm a 200 response. Don't move on to step 3 until you've seen the new key successfully authenticate.

3. Revoke the old key

1. Back on the API keys panel, find the row for the old key (the prefix + label make it easy to identify).
2. Click Revoke, confirm the inline prompt.
3. Refresh the consumer once more to make sure it's still working off the new key (not silently falling back to a cached old credential).

The revoke is immediate — the old key is rejected by the API middleware on the next call.

Multi-key concurrency

You can have multiple active keys at once. Both (or all) of them are independently valid until you explicitly revoke each one. Revoking key A has no effect on key B, even if they're identical scope-wise.

This is what makes the create-then-revoke flow zero-downtime: there's no moment where the consumer has neither a valid old credential nor a deployed new one.

Leak response

If a key may have been exposed, the priority order flips:

1. Revoke the leaked key immediately. Don't wait for a replacement to be ready — every minute the leaked key stays active is more exposure. If a replacement is already deployed (e.g. you rotated last week and the old key was still sitting active "just in case"), you've achieved zero-downtime by accident. Otherwise accept a brief outage on the affected consumer.
2. Audit the key's usage. The audit log shows when each key was last used and what scopes it carried. If the leaked key is READ_* only, the blast radius is bounded to read access on those scopes; the leaked key cannot mutate state.
3. Create + deploy a replacement on the cleanup path, with a fresh label that records the incident date.
4. Rotate any other credentials that may have leaked alongside it (most leaks are not isolated — if one secret hit a public repo, others likely did too).

Partner-staff workflow

PARTNER key rotation runs through the same flow at Partner → API keys, with one auth gate:

• Only PARTNER_OWNER and PARTNER_ADMIN roles can create or revoke PARTNER keys. PARTNER_STAFF can view the list but the controls are read-only for them.
• Rotating a PARTNER key does not invalidate any client-org permissions the partner has earned through linkage. The key is the authentication credential; the authorisation surface (which client organisations the partner can read into) is governed separately.

If you're a PARTNER_STAFF member and you need a key rotated, ask any PARTNER_OWNER or PARTNER_ADMIN on your team — they can do it from the same panel.

Quota note (forward-looking)

Once the daily-call-cap chokepoint lands, both the old and new keys will share the issuing user's daily quota during the rotation window. Rotating doesn't grant extra capacity — if you're already at the cap, both keys will hit DAILY_LIMIT together until the day rolls over (UTC midnight).

In practice this is a non-issue for the few-minutes-to-a-day overlap of a normal rotation. It only matters if you deliberately keep both keys active long-term, which we don't recommend (each active key is extra exposure surface for no operational benefit).

See also

• API keys — issue, scope, audit, and the READ_SENSITIVE danger-zone toggle.
• Agent API overview — what the keys actually authenticate against.