Property Access Reviews: Readiness Health Endpoint Checks for Cached API Credentials

When evaluating a cached API credential for readiness, an explicit observation age limit must be established. If the most recent observation is recent, the system can respond with "ready" without contacting the account API. However, if the observation is outdated and a refresh attempt is denied, the system should return "degraded."

This decision separates the responsibility of preserving last-known evidence for diagnosis from determining whether the node should receive traffic. It is crucial to understand that a process ping only confirms the process's responsiveness, not its readiness to perform assigned tasks. Making a direct call to the upstream account API on each probe introduces additional issues, such as increased authentication traffic and potential mass eviction of nodes upon upstream refusal.

Therefore, the freshness ceiling and the tolerance for refused traffic must be defined within the same architecture record.

The readiness health endpoint checks should validate an API credential based on four invariants. Firstly, the response must distinguish process availability from credential evidence. Secondly, successful observations should only record the minimum required fields for the review, including a pseudonymous credential key, allowed capability set, tier class, observation time, and result.

Thirdly, a failed refresh should not overwrite the last successful observation. Lastly, neither the endpoint nor its telemetry should emit the credential secret. Evidence has a limited lifespan and should be considered expired. It is essential to limit access to secrets, apply the principle of least privilege, rotate secrets regularly, and audit secret usage. The cache stores an assessment of a credential, not the credential value itself.

The freshness of the cached evidence is determined by the policy, not a fixed time frame. For instance, if 24 application nodes are probed every 10 seconds, a direct check would generate 144 upstream validations per minute. By employing a shared observation with a 60-second interval, the refresh demand can be reduced to approximately one validation per minute per credential, assuming refreshes are coalesced.

The number of nodes, interval, cache scope, and credential partition can all impact the design inputs and the resulting arithmetic. The failure boundaries are intentionally unequal. An invalid credential should be treated as authoritative evidence and result in "not_ready." A refused or timed-out refresh is considered an observation failure and should lead to "degraded" while preserving the previous evidence within its maximum stale window.

After this window, the system transitions to "not_ready." It is crucial to handle fast failures effectively, as refusal can be ambiguous. The state machine should have three distinct states, but they should not be collapsed into a single Boolean value.

There are four states for the endpoint, each corresponding to a specific traffic decision and review meaning. A "ready" status indicates that the credential and required tier are confirmed within the fresh window. A "degraded" response signifies that the current evidence exists but is beyond the fresh window. If the last confirmation is within the stale window, the system responds with "degraded" and labels the evidence as stale.

If the credential is rejected, the tier is insufficient, or there is no evidence beyond the stale window, the response is "not_ready." The "not_ready" status should only be reached when there is no defensible evidence. The distinction between "degraded" and "not_ready" helps manage two different budgets: one for availability and the other for certainty. By setting an explicit stale window, a compromise can be reached that balances the two budgets.

The critical path should be protected behind a single observable request to ensure a cheap and deterministic public probe. A scheduler or single-flight refresh path should handle upstream validation, while the request handler reads the resulting snapshot. This prevents concurrent probes from multiplying calls when the cache expires.

The Node.js service can exercise the critical path using a curl request that returns an example contract for the service, without exposing any sensitive information. The handler should return a success-class HTTP response for "ready," a distinct documented response for "degraded," and a failure-class response for "not_ready." The exact mapping of HTTP statuses to traffic controller contracts should be carefully considered and tested during deployment.

The refresh worker should include a single-flight guard, a short request deadline, and bounded retry with jitter to minimize upstream work when refusal is already the signal. The previous successful snapshot should remain immutable, and a new snapshot should only be published after confirming both the credential and required tier. Rejection should be classified separately from transport issues.