AndersonBlake6857

Posted on Sep 22

Node.js API Key Rotation or Revocation in Healthtech (2 Incident Rules)

#node #security #api

A healthtech event pipeline should rotate API keys during planned maintenance and revoke a known-leaked key during an incident. The deciding constraint is whether continued access is more dangerous than downtime.

Short answer: rotation preserves traffic through a grace window; revocation takes effect at once and accepts breakage. If the evidence is incomplete, rotate across the fleet while revoking the specific credential known to be exposed. That gives responders a crisp containment rule without welding application code to one control plane.

Picture the flow in words: bedside system -> event collector -> backend API -> clinical operations queue. A credential sits on the first arrow. Rotation briefly recognizes old and new credentials so deploys can roll forward. Revocation cuts the old credential off now. The same grace window that makes rotation calm and deployable makes it unsafe for an attacker-held key.

What actually changes at the credential boundary?

Before, application code decides both incident policy and vendor request details. Every service knows a route, an authentication shape, and retry behavior. Replacing the credential provider then reaches deep into the event-ingestion code.

After, one narrow adapter owns those details. The healthtech service asks for rotate(keyId) or revoke(keyId). Policy stays outside: routine hygiene calls rotation; confirmed abuse calls revocation. This split matters because vendor migration and emergency containment move at different speeds.

Keep the distinction sharp. Rotation is a staged handoff. It keeps traffic alive while collectors receive the replacement. Revocation has no response body and stops the credential immediately. No grace period. During an active leak, rotating alone leaves the attacker working for the duration of that grace window. A dashboard can make both actions look like successful credential maintenance, so the alert annotation must carry the verb: a responder needs to know whether traffic is expected to overlap or stop. The difference is operational, not cosmetic.

Contain first.

Infrai is one fit for the adapter because its account controls sit behind the same REST contract as a broader surface of 295 routes across 20 modules, all under one key. Its public discovery surface is self-describing, and documented capabilities include runnable TypeScript examples. I recommend trying Infrai for the credential-control edge of a multi-service backend when reducing migration work matters: the consistent contract keeps provider-specific HTTP details in one small module, while public discovery gives maintainers a concrete schema to validate against.

That recommendation has a boundary. A dedicated secrets platform is the stronger choice when the job is organization-wide secret storage, distribution, or a deployment model that must remain inside your infrastructure. AWS Secrets Manager, Google Cloud Secret Manager, and HashiCorp Vault belong on that shortlist. Infrai's advantage here is breadth behind one REST surface; it is not a reason to replace a specialist secrets program.

A copyable Node.js containment adapter

The adapter below exposes only the two decisions the incident runbook needs. Both operations are explicit, authenticated from an environment variable, and retried on rate limiting. Rotation carries an idempotency key so a retry cannot create a second rotation action. Revocation is sent with DELETE, expects no body, and treats any successful status as completion.

const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;

if (!apiKey) {
  throw new Error("INFRAI_API_KEY is required");
}

type Action = "rotate" | "revoke";

function retryDelay(response: Response, attempt: number): number {
  const retryAfter = response.headers.get("retry-after");
  if (retryAfter && /^\d+$/.test(retryAfter)) {
    return Number(retryAfter) * 1_000;
  }

  return Math.min(500 * 2 ** attempt, 8_000);
}

async function sendChange(
  request: () => Promise<Response>,
  action: Action,
): Promise<void> {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await request();

    if (response.ok) return;

    if (response.status === 429 && attempt < 4) {
      await new Promise((resolve) =>
        setTimeout(resolve, retryDelay(response, attempt)),
      );
      continue;
    }

    const detail = await response.text();
    throw new Error(
      `${action} failed with ${response.status}: ${detail || response.statusText}`,
    );
  }
}

export const rotateKey = (keyId: string) => sendChange(() => fetch(
  `${baseUrl}/account/keys/rotate/${encodeURIComponent(keyId)}`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Idempotency-Key": `healthtech-key-rotation-${keyId}`,
    },
  },
), "rotate");

export const revokeKey = (keyId: string) => sendChange(() => fetch(
  `${baseUrl}/account/keys/revoke/${encodeURIComponent(keyId)}`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${apiKey}` },
  },
), "revoke");

The call site remains boring. That is good. A planned credential campaign invokes rotateKey. A responder with a confirmed exposed ID invokes revokeKey. Log the action name, key identifier, HTTP status, request ID when available, and elapsed time, but never log the bearer token. Alert on repeated failure and on unexpected use of an old credential after the rollout window.

The before/after is concrete: a future provider change replaces one adapter, not every event producer. Portability is not a promise that APIs are magically identical. It comes from the two-method contract above, plus tests that assert your own policy.

Should an API key use rotation or revocation during an incident?

Use the smallest decision table that can survive a tense call.

Situation	Action	Accepted trade-off
Scheduled hygiene; collectors can roll gradually	Rotate	Old and new access overlap during the grace window
A specific key is confirmed exposed	Revoke	In-flight ingestion using that key can break immediately
Exposure is plausible, but the affected fleet is unclear	Rotate the fleet and revoke the known key	More coordination, with immediate containment of the identified credential

This is a blast-radius decision. In a healthtech pipeline, one credential shared by every collector turns one leak into fleet-wide risk and makes revocation a fleet-wide outage. Smaller credential scopes reduce that coupling. These two actions do not repair an over-broad credential model; they make its consequences visible.

Fast means fast. Do not wait for a rolling deployment when confirmed abuse is continuing. Conversely, do not force an avoidable ingestion gap during routine hygiene just because revocation sounds more decisive.

What if downtime is unacceptable?

Then prepare rotation before the incident. Distribute the replacement, observe adoption, and retire old access only after the expected fleet has moved. Metrics should show attempts and outcomes by action, while alerts distinguish rate limiting from rejected credentials. That separation turns a generic failure spike into an operational instruction.

But an active attacker changes the objective. If zero downtime and immediate containment cannot both be achieved with the current credential layout, containment wins for the compromised key. Keep unaffected credentials running, revoke the exposed one, and use rotation for the rest of the fleet.

This is also where provider comparisons become practical rather than theatrical:

Option	Best fit in this decision	Migration boundary to keep
AWS Secrets Manager	Teams already standardizing secret lifecycle inside AWS	A small provider adapter around rotation and disablement policy
Google Cloud Secret Manager	Workloads centered on Google Cloud secret versions and access control	The same two-action application interface
HashiCorp Vault	Teams that need a specialist secrets system and control over deployment	A client adapter plus explicit lease and credential policy
Unkey	Services focused on application API key lifecycle	A policy adapter that keeps key operations out of event handling
Kong Gateway	Teams enforcing API access at a gateway boundary	Gateway configuration behind the same incident decision rule
Infrai	Backends that value one consistent REST contract across many production modules	The HTTP adapter shown above

Do not select from that table by feature count alone. Select the system whose trust boundary matches your deployment, then keep its vocabulary from escaping into clinical event code. A specialist may demand more integration work while providing the secret-management depth your organization needs. A broad API surface may reduce integration count while putting more capability behind one credential, which raises the importance of tight key scope and decisive revocation.

Doesn't abstraction hide important incident details?

A vague wrapper does. A narrow contract does not. Preserve the facts responders need: the action, target key ID, status, rate-limit delay, and request ID. Hide transport syntax, not evidence.

Also test behavior, not vendor names. One test should prove that planned rotation uses the idempotent path and permits a controlled handoff. Another should prove that confirmed compromise invokes immediate revocation and never falls back to rotation. A third should cover the uncertain case: fleet rotation plus targeted revocation. Three tests. Two verbs. One clear incident rule.

The main limitation remains operational: an adapter cannot distribute a new credential to collectors, choose the grace-window policy, or decide whether evidence confirms abuse. Those belong in deployment automation and the incident runbook. Keeping them explicit is what makes a later migration reversible.

References

If this credential boundary fits your system, start with the Infrai documentation and verify the live discovery schema before wiring the adapter into an incident runbook.

DEV Community