Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tallyforagents.com/llms.txt

Use this file to discover all available pages before exploring further.

Rotation is the operational hygiene that lets you respond to a leak, finish a key’s lifecycle, or just stay on top of credential hygiene. Tally gives you three different rotation flows, and they behave differently — this guide walks through all three.

​
When to rotate

TriggerWhat to rotate
Suspected leak (key in logs, screenshot, accidental commit)Whatever leaked, immediately
Routine schedule (quarterly is reasonable)API keys, optionally agent permissions
Team member leavingAPI keys they had access to
Privy / KMS infrastructure changeAgent permissions (key generation flows differently)
Webhook receiver redeployed with new secret storeWebhook secrets
Don’t rotate without a reason. Each rotation has operational risk; routine cycling is good practice but skip it if there’s no policy.

​
API key rotation

The API key flow is the highest-touch. You probably have keys in production environments, staging, CI, and personal .env.local files; rotating means coordinating all of them. Tally gives you a 24-hour grace window to make this manageable: when you rotate a key, the previous one keeps authenticating for 24 hours while you roll the fleet.

​
Step by step

  1. Open the dashboard’s API keys tab. Find the key you want to rotate.
  2. Click Rotate. Tally mints a fresh key, stamps the old one with a rotatedAt timestamp + a gracePeriodEndsAt 24 hours out, and shows you the new plaintext exactly once. Copy it.
  3. Roll out the new key to every consumer. Production env vars, staging, CI secrets, anywhere the old key was used. The order doesn’t matter — both work simultaneously during the grace window.
  4. Verify all consumers are on the new key. Check your deploy logs, CI runs, anything that authenticated successfully against Tally in the last hour. If a consumer is still on the old key after the grace window, it’ll start getting 401s.
  5. (Optional) Revoke the old key early if you’re confident the fleet has rolled. Hard revocation is immediate — distinct from the rotation grace expiring naturally.
The dashboard’s key list shows the status — Active, Rotated · grace, Revoked, Rotated · expired — with a live countdown for keys in the grace window so you can see exactly how long the old key has left.

​
Leaked key — emergency flow

The 24-hour grace window is a comfort, not a requirement. If a key leaks publicly (committed to a public repo, posted in a screenshot, etc.):
  1. Rotate immediately. The new key starts working instantly.
  2. Hard-revoke the old one instead of waiting for the grace to expire. Revocation is immediate and irreversible — no grace.
Tally’s leaked-key scanner watches public commits and revokes proactively, but the safe play is to revoke yourself the moment you notice.

​
Agent permission rotation

Agent permissions have their own signing keys (the P-256 keypair Tally generates per (agent, wallet) pair). Rotating one of these means swapping the signing key while keeping the policy bounds identical. You’d do this if:
  • You suspect a Tally infrastructure compromise affected the signing key for a specific permission.
  • You’re rotating as part of a quarterly cadence.
You wouldn’t rotate a permission to change the policy — that’s an edit, not a rotation. Edits update the policy in place; rotations replace the key.

​
Step by step

  1. Open the agent’s detail page in the dashboard. You’ll see one card per active permission.
  2. Click Rotate on the permission. Tally generates a fresh keypair, registers the public half with Privy as a new additional signer, creates a Privy policy that mirrors the old one exactly, and persists a pending AgentSigner.
  3. Sign the addition with your passkey. Same flow as the initial grant.
  4. The old signer is revoked automatically once the new one activates. The audit log links the two with a rotated_from reference.
The terms must mirror the source exactly — same per-tx max, same daily cap, same allowlists, same expiry. If you want to change anything, edit the policy in place first, then rotate. Mixing rotation with term changes makes the audit log harder to reason about.

​
Editing a policy in place

If the goal is “make the per-tx max bigger” or “extend the expiry by a month,” don’t rotate — edit. From the permission card:
  1. Click Edit.
  2. Change the field(s) you want.
  3. Sign the change with your passkey.
The same AgentSigner stays in place; only the policy fields change. The change is mirrored to Privy via updatePolicy() and logged in the policy change log.

​
Webhook secret rotation

Webhook secrets don’t have a grace window today — rotation is immediate.
  1. Open the webhook’s detail page.
  2. Click Rotate secret. A new whsec_test_… (or whsec_live_…) is generated and shown exactly once.
  3. Update your handler’s env var with the new secret. Same env var name; new value.
Until step 3 completes, your handler will reject every delivery as signature_mismatch. Tally retries non-2xx for 24 hours, so a few minutes of mismatched secret won’t lose events — but anything beyond the retry window does. A 24-hour grace window for webhook secrets is on the roadmap for parity with API keys.

​
Verifying rotation worked

Confidence checks after each rotation:
  • API key: make a tally.agents.list() call from a service that’s been redeployed with the new key. It should succeed; the request counter on the new key (visible in the dashboard) should go up.
  • Agent permission: trigger a small test payment via the agent. The audit log should show the new signer’s id, not the old one’s.
  • Webhook secret: trigger an event (a real payment, or replay a recent delivery). Your handler should accept it.
If anything fails, you’ll see structured errors — unauthenticated for keys, signature_mismatch for webhooks. Fix forward; don’t roll the rotation back unless you have to.

​
Where to go from here

  • API keys — full lifecycle, status states, leaked-key scanner.
  • Permissions — what a policy bounds and how rotation differs from edit.
  • Webhooks — retry schedule, replay, why 24-hour secret-grace would be parity.