Begin with the status and error_code. Record only the key prefix when
correlating a failure; never paste the full key into tickets, chat, logs, or
shell history.
Symptom guide
| Symptom | Check | Resolution |
|---|---|---|
| Key is rejected immediately | Exact X-Api-Key header, copied value, and key existence |
Load the credential from the secret manager and avoid whitespace or truncation |
| A previously valid key returns 401 | Expiration and whether the key was deleted or rotated | Deploy the current key or create a replacement with the intended expiry |
| Request returns 403 | Required endpoint permission and key permission list | Create a least-privilege replacement with the required permission |
| Organization-management route rejects the key | Route family | Use a bearer JWT for organization management; keys are for /api/service/* |
| Key works for the wrong intended workload | Service/environment association | Revoke it and issue separate scoped keys per workload and environment |
| Response returns 429 | Rate-limit headers and request loop | Honor reset/retry guidance, bound concurrency, and eliminate uncontrolled polling |
last_used_at does not change |
Whether the request reached AuthOS with this key | Check proxy routing and credential selection, then make a harmless authorized request |
| New key was lost after creation | One-time reveal behavior | Delete the unusable key and create a replacement; the plaintext cannot be retrieved |
Safe rotation check
- Create a replacement with the same required permissions and a deliberate expiry.
- Store it directly in the target secret manager.
- Deploy and verify a harmless service API read.
- Monitor failures and
last_used_at. - Delete the old key only after every consumer has moved.
For generic response parsing and retry rules, see API error handling.