This document describes the authentication flow and incident response procedure for the internal API gateway.

All external requests pass through the gateway, which validates the access token in the request header before routing to internal services. Tokens are valid for thirty minutes from issuance, and refresh tokens expire after fourteen days. A refresh token is discarded after a single use; if reuse is detected, the entire session lineage is invalidated.

Permissions are role based. Roles are divided into three levels: administrator, operator, and viewer. Each role is scoped to a resource group. A higher role does not automatically inherit the permissions of a lower one. Required permissions must be granted explicitly, a design choice intended to prevent over-provisioning through inheritance.

Incidents are classified from severity one through severity four based on blast radius and duration. Severity one means a full service outage, severity two a failure of core functionality, severity three degraded partial functionality, and severity four an internal error with no user impact. Severity one and two automatically page the on-call engineer.

If the error rate exceeds three times the baseline within ten minutes of a deployment, an automatic rollback is triggered. If the automatic rollback fails, redeploy manually by pinning the previous version tag. Deployments containing database schema changes are excluded from automatic rollback, so a reverse migration script must be prepared in advance.

Incidents of severity two or higher require a postmortem document within three business days. The document must include the time of occurrence, how it was detected, the actions taken, the root cause, and the measures that will prevent recurrence. The focus is on improving systems and procedures rather than assigning blame.