API key design for AI agents: test mode, live mode, and rotation

What good API keys communicate

A bot operator should be able to tell whether a key is test or live at a glance. Prefixes help humans avoid accidents and help logs become searchable.

For agent payments, keys also need rotation because they often live inside job runners, bot hosts, and environment variables that change over time.

Key model

• Use visible prefixes for test and live keys.
• Store only hashed keys server-side.
• Show the secret once during creation.
• Let operators revoke keys without deleting wallets.
• Track last-used timestamp and source metadata.

Environment layout

VIACLAVE_API_KEY=vc_test_replace_me
VIACLAVE_MODE=test
VIACLAVE_WEBHOOK_SECRET=whsec_replace_me

Runtime guard

Add a simple runtime check so a development bot does not start with a live key by accident.

function assertExpectedMode() {
  const key = process.env.VIACLAVE_API_KEY || "";
  const mode = process.env.VIACLAVE_MODE;

  if (mode === "test" && !key.startsWith("vc_test_")) {
    throw new Error("Expected a test API key");
  }

  if (mode === "live" && !key.startsWith("vc_live_")) {
    throw new Error("Expected a live API key");
  }
}

Rotation plan

• Create a new key before revoking the old one.
• Deploy the new key to all bot workers.
• Watch last-used timestamps for both keys.
• Revoke the old key only after traffic moves.
• Keep an incident note explaining why rotation happened.

ROI

Good key hygiene prevents expensive mistakes. One leaked live key can move real funds if it also has access to funded wallets. Mode separation and rotation reduce blast radius and make security reviews faster.