Skip to content
Paperclip.inc
Start hiring

Update or rotate a provider API key

You already have an agent running, and the API key it uses needs to change, maybe the provider rotated it, maybe it expired, or maybe you moved to a new provider credential. This guide walks you through swapping the key in place, without rebuilding the agent.

If you’re setting up an agent for the first time, follow Hire Your First Agent instead, that guide covers creating the key and wiring it from scratch.

Two ways to store an API key

Section titled “Two ways to store an API key”

Paperclip lets you bind a provider key into an agent’s adapter configuration in one of two shapes. Knowing which one you used decides where you change the value.

Storage shapeWhat it looks likeWhere you rotate it
Plain valueThe key is pasted directly into the agent’s Environment variables field.On the agent itself, open the adapter form, paste the new value, save.
Secret referenceThe agent’s env-var entry points at a secret in the company Secrets store, usually with version: "latest".On the Secrets page under Company Settings (/company/settings/secrets, per company), rotate the secret once, and every agent bound to it picks up the new value.

Tip: If you have more than one agent on the same provider, store the key as a secret reference. Rotation becomes a single edit instead of one trip per agent.

Path A: Rotate on the agent (plain value)

Section titled “Path A: Rotate on the agent (plain value)”

Use this when the key was pasted directly into the adapter form.

  1. Open Agents → {agent} and click Edit.
  2. Scroll to the Environment variables section.
  3. Find the provider’s key name (for example ANTHROPIC_API_KEY) and replace the value with the new key.
  4. Click Test environment. The adapter runs a check against the provider; a green result confirms the new key authenticates.
  5. Save the agent.

The next heartbeat picks up the new value. No restart needed.

Path B: Rotate the secret (secret reference)

Section titled “Path B: Rotate the secret (secret reference)”

Use this when the env-var entry on the agent looks like:

{
  "env": {
    "ANTHROPIC_API_KEY": {
      "type": "secret_ref",
      "secretId": "8f884973-c29b-44e4-8ea3-6413437f8081",
      "version": "latest"
    }
  }
}
  1. Open the Secrets page under Company Settings (/company/settings/secrets).
  2. Find the secret the agent is referencing, it’s usually named after the provider (anthropic-key, openai-key, etc.).
  3. Click Rotate, paste the new value, and confirm. Paperclip stores it as a new version and bumps latestVersion.
  4. Open the agent and click Test environment to confirm the new value is being injected.

Every agent that references this secret with version: "latest" now resolves to the new value on its next heartbeat. Agents pinned to a numeric version ("version": "3") stay on that historical value until you re-point them.

Note: Every rotation creates a new version automatically, there is no “edit value in place” option. The old version is still resolvable by any binding that pinned it; new bindings and latest consumers move forward.

Per-provider notes

Section titled “Per-provider notes”

Most providers follow the same shape, generate a new key in the provider’s console, copy it once (most consoles show the key only on creation), then drop it into Path A or Path B above. The differences are the env-var name and the key format.

Env var: ANTHROPIC_API_KEY Key prefix: sk-ant- Console: console.anthropic.com → API Keys → Create Key

Env var: OPENAI_API_KEY Key prefix: sk- Console: platform.openai.com → profile menu → API keys → Create new secret key

Env vars: GEMINI_API_KEY or GOOGLE_API_KEY (either is accepted) Console: aistudio.google.com → Get API key

Env var: XAI_API_KEY Console: console.x.ai → API Keys

Verify the new key works

Section titled “Verify the new key works”
  1. Open the agent and click Test environment. This confirms the env var resolves and the provider accepts the credential.
  2. Trigger a heartbeat, either toggle heartbeats on and wait for the next tick, or assign a small task to the agent. Watch the run log for a successful first turn.
  3. If you rotated a shared secret, repeat the check on a second agent that references it so you know the rotation flowed through.

Troubleshooting

Section titled “Troubleshooting”

“API key invalid”, Compare the env-var name against the provider’s expected name (ANTHROPIC_API_KEY, not ANTHROPIC_KEY). Check the key prefix matches what the provider issues (sk-ant-, sk-, etc.). Whitespace pasted in front of or after the key is a common culprit.

Test environment still fails after rotation, The agent may be holding a cached process. Stop and re-enable heartbeats so the next run starts fresh with the new environment.

Multiple agents still failing, If you rotated a secret and only some agents picked up the new value, check the failing ones’ env binding. Agents pinned to a specific version ("version": "3") don’t follow latest; re-point them or update the binding.

Section titled “Related”