Cohere API Key Rotation: Zero-Downtime Rotation and the Leaked-Key Runbook

Getting your first Cohere key working is a five-minute job, and there is asetup guidefor it. This page is about the part nobody writes down: the credential you already have is a liability with an age, and at some point it has to be replaced — on a schedule, when someone leaves, or at 2am because it turned up in a public repository.

Almost every painful key rotation fails for the same structural reason: the team treats it as editing a secret rather than running two credentials in parallel. Editing in place guarantees a window where the deployed configuration and the set of valid keys disagree, and the length of that window is however long your slowest deploy target takes to pick up the change. Overlap eliminates the window entirely.

Rotation Is a Four-Phase Overlap, Not an Edit

The whole technique is that two Cohere keys are valid at the same time for as long as it takes every consumer to move. Nothing clever happens in any individual step; the safety comes entirely from the order.

Phase 3 is where the discipline lives. "I updated the secret" is not evidence; zero usage on the old key is. A long-running process that read COHERE_API_KEY at startup will happily keep using the old credential for days after the secret store was updated, and you will discover this at the exact moment you revoke.

The Cohere-Specific Trap: Trial Keys and Two Client Paths

Cohere issues more than one kind of key, and they are not interchangeable in production. A trial key is free, heavily rate limited, and intended for evaluation; a production key is the one that carries real throughput. The failure mode is not that a trial key stops working — it is that it keeps working, just slowly and with a low ceiling, so a service that shipped with a trial key looks healthy in staging and then throttles under real load. Rotation is the natural moment to catch this: when you enumerate your credentials, record the key type next to each one, and treat any trial key found in a production environment as a finding rather than a footnote.

The second trap is structural. Cohere's surface spans distinct capabilities — generation, embeddings, and rerank — and retrieval stacks commonly construct separate clients for them, often in different modules written by different people at different times. Rotate the key in the chat client, redeploy, watch the dashboard go green, and the rerank client can still be holding the old credential from a config path nobody remembered.

The defence is the same single-construction-point rule that solves it everywhere else, applied per-provider: one module builds every Cohere client, reads the credential once, and every capability imports from there. Until that refactor lands, your rotation checklist needs an explicit line per capability, and the verification step has to exercise a real call on each — an embeddings call and a rerank call, not just a chat completion.

Reading the Credential So Rotation Is a Config Change

A rotation is only as fast as the slowest consumer, and the slowest consumer is always the one that read the key once, at import time, into a module-level constant. Build every Cohere client from one place, read the credential at call time, and a rotation becomes a config change rather than a redeploy.

// ONE module constructs every Cohere client for the whole codebase.
// Nothing else in the repo reads COHERE_API_KEY directly.

function credential() {
  // Read at call time, not at import time — a process that has been
  // running for a week must be able to pick up a rotated key.
  const key = process.env.COHERE_API_KEY;
  if (!key) throw new Error('COHERE_API_KEY is not set');
  return key;
}

export async function callCohere(path, body) {
  const res = await fetch(`https://api.cohere.com/v2${path}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${credential()}`,
      'Content-Type': 'application/json',
      // Tag every request with which key issued it. During a rotation
      // this is how you prove the old credential has actually drained.
      'X-Key-Id': process.env.COHERE_API_KEY_ID ?? 'unlabelled',
    },
    body: JSON.stringify(body),
  });

  // 401 is fatal. Retrying it during a revocation turns a clean
  // cutover into a retry storm against a dead credential.
  if (res.status === 401) {
    throw new Error('Cohere: credential rejected — rotated or revoked, do not retry');
  }
  return res;
}

The X-Key-Id line is the cheap trick worth stealing. Emit the key identifier — never the key itself — into your own logs, and phase 3 stops being a guess: you can watch traffic on the old identifier fall to zero across every service before you revoke anything.

The Leaked-Key Runbook: First Ten Minutes

A leaked Cohere key is not primarily a security incident with a fixed cost. It is a metered credential that somebody else is now spending, and every minute of deliberation has a price. Work the list in order.

1. Decide whether to revoke first or rotate first. Visible abuse — usage you cannot attribute, a spend curve that is not yours — means revoke now and accept the outage. No evidence of abuse means rotate first and revoke a few minutes later with no downtime at all.
2. Issue the replacement in the Cohere dashboard and push it through the same four-phase overlap. Do not shortcut the inventory step just because you are in a hurry; a half-rotated stack under incident pressure is how a ten-minute problem becomes a two-day one.
3. Delete the exposed key once traffic on it is zero. Delete rather than disable.
4. Pull the usage record for the entire window the key was exposed — not since you noticed. The exposure started when the secret was written, not when it was found.
5. Purge the secret from history. A key committed to git is still in the reflog, in forks, in CI caches, and in any build log that echoed the environment. Rewriting the commit is not sufficient on its own, which is precisely why revocation comes first.
6. Close the process gap. Ask how a credential reached a location your secret store does not control, and fix that. A rotation that does not end in a changed process is a rotation you will be repeating.

How a Compromised Key Actually Presents

This is the part that makes credential incidents hard to spot: almost none of the symptoms look like a security event. Five of the six rows below return a perfectly ordinary HTTP status.

The through-line: with a single shared key, every one of these is indistinguishable from an ordinary engineering problem, and teams reliably spend days debugging the wrong layer. Split keys per workload and the same anomalies become attributable in the first hour, because the usage that does not belong is sitting on a credential with a name.

A Rotation Schedule Worth Actually Keeping

• Every 90 days for production credentials, calendared, with an owner. An unowned schedule is a decoration.
• On offboarding, for every key the departing person could read — which, if you have a shared secret store, is a bigger list than the one they personally created.
• On exposure, immediately — including "probably fine" exposure like a screenshot, a support ticket, a pasted log, or a shared no-code workflow. Probability is not a control.
• Before an audit or a security questionnaire, because the first question is always the age of the credential and the second is when you last practised the procedure.
• After any incident in which the key was read out of a running environment by a human, even a trusted one.

One more discipline that costs nothing: rotate on a boring Tuesday when nothing is on fire. A rotation procedure that has only ever been executed during an incident is a procedure you are testing in production at the worst possible moment.

Where to Send Traffic If a Revocation Goes Wrong

A botched rotation is an outage you caused, and it deserves the same fallback path as one the provider caused. Each of these runs on separate infrastructure and a separate credential, so a Cohere key problem does not follow you there.

Choosing a destination is its own problem — see thefallback ranking guidefor how to decide whether the answer you get back is worth the same, and thefailover guidefor the cutover mechanics.

Frequently Asked Questions

Related Cohere Guides

• Cohere API Key Setup Guide
• Cohere API Error Codes Explained
• Cohere API Rate Limits Explained
• Cohere API Cost Attribution Guide
• Cohere API Data Privacy & Retention
• Cohere API Monitoring Guide
• API Authentication & Security: The Complete Guide