In your process, not in front of it
Why Keyring is an SDK and never a proxy, and what that costs and buys.
A gateway in front of your API is a network hop on every request, a second deployment to run, a second place for TLS to terminate, and a single point of failure that is not yours. Keyring puts the same functions inside your process instead.
What runs where
| In your process, on the request path | In the background | On the control plane |
|---|---|---|
| Parse the key, SHA-256 it, look it up in memory | Poll the project's policy delta every 5 s | Mint, rotate, revoke, edit; the dashboard; the audit log |
| Check scopes, expiry, the route rule | Persist a snapshot to disk | Rate-limit counters and idempotency records |
| Resolve resources for the key's environment | Ship usage events, gzipped, every second | Usage aggregates and billing |
| Charge rate limits (one round trip, bounded) |
Verification is a SHA-256, a map lookup and a constant-time compare, measured at a p50 of 3.2 microseconds with 10,000 keys cached. Keyring.handle() is synchronous, and so are the policy store's get() and status(), so a remote lookup on the hot path cannot be written.
The one request-path call that leaves the process is the rate-limit check, when the key has limits, and it is bounded at 500 milliseconds with open as the default when it fails. Idempotency is the other, and it only runs for requests that carry the header.
What it costs
- Memory. Every key in the project is cached, at roughly 855 bytes per key on a typical shape. The bound raises itself to 38,000 keys, about 31 MiB; a project larger than that on a node that has never served refuses to start rather than serve an incomplete cache.
tenantIdsnarrows a node to the tenants it serves. - A window. A revocation lands within one poll, at most 5 seconds.
revoke?wait=trueturns that into a receipt. - The fail-open decision is yours. The SDK cannot ask anyone when the control plane is unreachable, so what it does then is configured per route.
What it buys
Keyring's outage is not yours. A control plane that is down stops rotations and revocations from landing, and stops nothing else: every node keeps verifying from its cache, and a node that restarts hydrates from its disk snapshot. The one thing an outage takes with it is exactly-once for callers that sent Idempotency-Key, and that is by design.