Key Health & Re-authentication
A pooled key that dies does not stop your agents — it quietly degrades them. SpiderGate takes the failing key out of rotation, tells apart a bad minute from a dead credential, and emails the one person who can replace it.
A failing key removes itself
Three consecutive failures mark a credential unhealthy and routing skips it. Nothing about the request path changes: the rest of the pool absorbs the work while the broken key stops taking a share of your traffic. On a shared pool this is the difference between one dead key being a non-event and it failing a slice of every minute until somebody notices.
Skipped, not failed
An unhealthy credential is excluded from selection. Callers see no error and no change in the request path, because a healthy key served it instead.
Driven by real outcomes
Health comes from what actually happened to your requests, not a synthetic probe. A sweep every ten minutes acts on what those outcomes recorded.
A bad minute is not a dead key
Rate limits and timeouts look identical to a revoked key in the logs and are nothing like it in nature. Treating them the same produces an hourly oscillation where a dead key is pulled, restored, and fails again — poisoning a slice of traffic each cycle. SpiderGate separates the two, and the separation is most of the value.
Transient: heals itself
Twenty minutes unhealthy with no authentication errors and the credential returns to the pool automatically. No human is involved, because none is needed.
Terminal: retired for good
Three authentication failures inside 24 hours deactivate the credential outright. It cannot be auto-recovered back into the pool, so the cycle ends.
Tell the person who can fix it
An alert sent to everyone is an alert nobody acts on. The contributor who added the key gets the re-authentication link; brand admins get a single daily digest naming which keys are down and who to chase for each. If you run client work, that digest is the difference between hearing it from your own dashboard and hearing it from your client.
Three reminders, then silence
At most three emails, 48 hours apart, and never inside the recipient's quiet hours. A deferred reminder waits for their morning rather than spending one of the three at 02:46.
One digest a day for admins
At 09:00 in each admin's own timezone, split into newly failed and still unhealthy, each row naming the contributor who owns the key.
Re-authenticate in place, do not rebuild
A key in a pool is not just a secret. It carries sharing settings, limits, a usage policy, quotas and history, and rebuilding it means reconstructing all of that from memory. Re-authentication replaces only the secret: same key id, same sharing, same limits, same history, and the engine reloads without a restart.
// The contributor opens the emailed link. No login, no dashboard seat.
// Link lifetime: 120h, chosen to outlast the full 3 x 48h reminder cycle.
POST /api/v1/gate/reauth/{token}/api-key // paste a fresh key
POST /api/v1/gate/reauth/{token}/oauth/start // or re-login for OAuth
POST /api/v1/gate/reauth/request-new-link // expired? self-service
// A new link is only ever emailed to the contributor on record,
// never to an address supplied in the request.