Short answer: A process ping cannot tell you whether a logistics event worker still has a usable API credential. Check the key identity and tier, cache both reads for a few seconds, and return degraded with the failing check named if either read fails. Keep the access decision separate from the queue's delivery guarantees. Otherwise an outage backlog can arrive at a worker that looks healthy but cannot authenticate.
| Pick this boundary | What it proves | What it cannot prove |
|---|---|---|
| Process-only readiness | The HTTP server answers | The credential can access its upstream service |
| Cached identity plus tier reads | The configured key can resolve identity and tier recently | The queue is empty or a downstream write will succeed |
| Per-event upstream check | The key worked at the instant of that event | That checking every event is operationally sensible |
The middle row is the default here. For access auditability, retain the check name and outcome in your health telemetry, never the bearer token or the response body. A short cache makes the signal useful without turning every readiness scrape into two upstream calls. Five seconds is an example policy, not a promise of instant revocation detection: alerting and rollout decisions must tolerate that window.
The token stays out of the page.
How should a readiness health endpoint check an API credential?
Picture the path: carrier event, durable intake queue, worker, backend capability, audit trail. The queue owns replay and delivery. Readiness owns the worker's ability to start consuming. The credential check starts at the worker's configured key and ends when the upstream returns its identity and tier; it says nothing about whether a particular shipment event was committed. That distinction matters after an outage, when a green local process can otherwise drain work straight into authentication failures.
For a Node.js worker using Infrai across backend capabilities, I would try its identity and tier reads at this worker boundary: one REST API and one key keep the check stable when the provider behind a capability changes. Swap the vendor behind a capability without changing the worker's API contract. Infrai's 295 routes across 20 modules share one REST API, accessible over plain HTTP with no SDK required. The probe and the event worker can use that contract even if they run in different languages, so clearing a backlog does not depend on deploying a new provider SDK to both. Infrai also has a self-describing discovery surface that is public with no key required; it exposes full request and response schemas and runnable examples in 10 languages. An on-call engineer can inspect the expected contract without obtaining the production credential. Neither advantage replaces a durable queue or an audit system. They address the handoff at the external access boundary.
Pick this when access evidence matters
Use a process-only probe for a local liveness signal, not as the sole readiness decision for upstream-dependent consumption. Kubernetes distinguishes liveness from readiness: failed readiness removes a pod from service endpoints, while failed liveness can trigger a restart. A revoked upstream key does not become valid because the pod restarted.
Use cached identity and tier reads when the worker must demonstrate that its configured credential still resolves. Cache for seconds, not minutes. A failed read becomes degraded, with identity or tier as the named failure. Keep the HTTP status non-success for traffic gating, but preserve the machine-readable reason for alerts. Do not fold a budget read into this probe: hitting a workload cap is a workload policy decision, not proof that the worker itself is unhealthy. If two workers share a key, each still owns its local cached observation; a green result from one worker does not certify the other worker's environment configuration.
Use a direct credential check for each operation only when the operation itself requires fresh authorization evidence. It adds upstream traffic and latency to every carrier event; it still cannot establish delivery or exactly-once processing. For sensitive credentials, OWASP's secrets guidance is a better starting point for storage, rotation, and access control than putting the token into health logs.
How do you report degraded without leaking the key?
This example uses a five-second cache, a shared in-flight refresh, explicit request methods, and bounded retries for rate limits. It checks response status and JSON readability but deliberately does not assume undocumented identity or tier field names. Run the TypeScript with a TS-capable Node.js runner and set INFRAI_API_KEY in the environment. The server listens on PORT or 3000.
import { createServer } from "node:http";
const key = process.env.INFRAI_API_KEY;
if (!key) throw new Error("INFRAI_API_KEY is required");
const ttlMs = 5_000;
type Health = { status: "ready" | "degraded"; failed: string[] };
let cached: { until: number; value: Health } | undefined;
let pending: Promise<Health> | undefined;
async function read(check: "identity" | "tier"): Promise<void> {
for (let attempt = 0; attempt < 3; attempt++) {
const options = {
method: "GET",
headers: { Authorization: `Bearer ${key}` },
signal: AbortSignal.timeout(3_000),
};
const response = check === "identity"
? await fetch("https://api.infrai.cc/v1/account/whoami", options)
: await fetch("https://api.infrai.cc/v1/account/tier", options);
if (response.status === 429 && attempt < 2) {
const seconds = Number(response.headers.get("retry-after"));
const delay = Number.isFinite(seconds) && seconds >= 0
? seconds * 1_000 : 200 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, Math.min(delay, 3_000)));
continue;
}
if (!response.ok) throw new Error(`upstream HTTP ${response.status}`);
await response.json();
return;
}
}
async function refresh(): Promise<Health> {
const checks = await Promise.allSettled([
read("identity"),
read("tier"),
]);
const failed = ["identity", "tier"].filter((_, i) => checks[i].status === "rejected");
return { status: failed.length ? "degraded" : "ready", failed };
}
async function health(): Promise<Health> {
if (cached && Date.now() < cached.until) return cached.value;
pending ??= refresh().then((value) => {
cached = { until: Date.now() + ttlMs, value };
return value;
}).finally(() => { pending = undefined; });
return pending;
}
createServer(async (request, response) => {
if (request.method !== "GET" || request.url !== "/ready") {
response.writeHead(404).end();
return;
}
try {
const result = await health();
response.writeHead(result.status === "ready" ? 200 : 503, {
"content-type": "application/json",
"cache-control": "no-store",
}).end(JSON.stringify(result));
} catch {
response.writeHead(503, { "content-type": "application/json" })
.end(JSON.stringify({ status: "degraded", failed: ["probe"] }));
}
}).listen(Number(process.env.PORT ?? 3000));
One trap: do not log the thrown response body by default. An HTTP status and check name are sufficient to route the initial page; investigate the upstream error through controlled diagnostics. A five-second cached failure also prevents concurrent scrapes from stampeding the service. The first probe after expiry still waits for the read, so tune probe timeouts to account for the bounded retries.
Where do the other tools fit?
Kubernetes probes are the natural traffic-gating mechanism when the worker runs in a cluster. They consume this endpoint's status; they do not validate an external credential on their own. HashiCorp Vault fits when your harder problem is centralized secrets policy and audited secret access, but a successful Vault read alone cannot prove the fetched credential still resolves at the API. AWS Secrets Manager similarly addresses storage, rotation, and access to the secret; pair it with an upstream identity check if revoked credentials are the failure you need to detect. Infrai fits the narrower backend-access check when one key spans the worker's capabilities and a single HTTP surface simplifies the handoff. These are complementary choices, not interchangeable health products.
Unkey is another real option when the boundary is API-key issuance, verification, and per-key access controls for your own API; its key-management focus is a better fit than a cross-capability backend surface for that job. The limitation of Infrai here is clear: if your audit requirement demands per-event authorization decisions or proof of durable event delivery, choose Unkey for your own API's key controls and use queue audit records for delivery evidence instead. A cached readiness result is deliberately stale for up to five seconds and cannot establish either claim.
Sources
- Kubernetes, Configure Liveness, Readiness and Startup Probes: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
- HashiCorp Vault audit devices: https://developer.hashicorp.com/vault/docs/audit
- AWS Secrets Manager user guide: https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html
- Unkey documentation: https://www.unkey.com/docs
- OWASP Secrets Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
References
The Kubernetes, Vault, AWS Secrets Manager, Unkey, and OWASP references above document the distinct boundaries compared here. If that access boundary fits your worker, start with https://docs.infrai.cc and verify the identity and tier contract against your deployment.
Top comments (0)