Runbooks

API key failures (401/500)

Symptoms

• Clients receive 401 Unauthorized or {"detail": "API key is missing"}.
• Service returns 500 with "API key error" on every request.

Checks

1. Confirm the request includes X-API-Key.
2. Verify the AUTH_API_KEY secret exists in Secret Manager.
3. Ensure the service account has secretmanager.versions.access.
4. Restart the service to reload secrets.

JWT verification failures

Symptoms

• 401 Unauthorized with errors such as "Invalid audience", "Issuer not allowed", or "Token expired".

Checks

1. Verify the expected_aud matches the token audience.
2. Confirm the issuer is included in allowed_issuers.
3. Validate expected_nonce if used by the client.

JWKS fetch errors

Symptoms

• 401 Unauthorized with "JWKS fetch error" or intermittent failures.

Checks

1. Confirm the issuer URL is reachable from the service.
2. Check if the issuer publishes a valid JWKS at /.well-known/jwks.json.
3. Look for networking/VPC connector issues.

CORS errors in client apps

Symptoms

• Browser console shows CORS blocked requests.

Checks

1. Confirm ALLOWED_ORIGINS includes the client origin.
2. Redeploy after changes.