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

Getting your first Perplexity 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 Perplexity 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 PERPLEXITY_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 Perplexity-Specific Trap: A Leaked Key Spends on Retrieval, Not Just Tokens

Perplexity's answering models are search-grounded, which means a request has a second cost component that a token-shaped monitor is structurally blind to: the retrieval itself. Anomaly detection built around "tokens per hour" — the design that works acceptably for a pure inference provider — can miss unauthorised Perplexity usage entirely, because the shape of the spend does not live in the dimension being watched.

Alert on request count and search volume for Perplexity, not on token throughput alone, and set the threshold against your own weekday baseline rather than against a plan limit. Unauthorised traffic on a stolen key rarely resembles your traffic; it is the flat overnight plateau on a workload that has a diurnal curve.

The other Perplexity-specific risk is where the key tends to live. Because the API is attractive to no-code builders, automation platforms, and browser-side prototypes, Perplexity keys leak through channels that never touch your source control: a shared automation workflow, a client-side fetch in a demo page, a screenshot in a support thread. Any key that has ever been pasted into a hosted automation tool or a front-end bundle should be treated as already disclosed and rotated on that basis — not on the basis of whether you can prove it was misused.

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 Perplexity 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 Perplexity client for the whole codebase.
// Nothing else in the repo reads PERPLEXITY_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.PERPLEXITY_API_KEY;
  if (!key) throw new Error('PERPLEXITY_API_KEY is not set');
  return key;
}

export async function callPerplexity(path, body) {
  const res = await fetch(`https://api.perplexity.ai${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.PERPLEXITY_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('Perplexity: 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 Perplexity 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 Perplexity API settings page 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 Perplexity 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 Perplexity Guides

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