본 문서는 사내 API 게이트웨이의 인증 흐름과 장애 대응 절차를 정리한 것이다.

1. 인증 개요
모든 외부 요청은 게이트웨이를 통과하며, 게이트웨이는 요청 헤더의 액세스 토큰을 검증한 뒤 내부 서비스로 라우팅한다. 토큰은 발급 시점으로부터 30분간 유효하고, 리프레시 토큰의 유효기간은 14일이다. 리프레시 토큰은 1회 사용 후 폐기되며, 재사용이 감지되면 해당 세션 계열 전체를 무효화한다.

2. 권한 모델
권한은 역할 기반으로 부여한다. 역할은 관리자, 운영자, 조회자 세 단계로 나뉘며, 각 역할은 리소스 그룹 단위로 스코프가 제한된다. 상위 역할이 하위 역할의 권한을 자동으로 포함하지는 않는다. 필요한 권한은 명시적으로 부여해야 하며, 이는 권한 상속으로 인한 과다 부여를 막기 위한 설계다.

3. 장애 등급 분류
장애는 영향 범위와 지속 시간에 따라 1등급에서 4등급으로 분류한다. 1등급은 전체 서비스 중단, 2등급은 핵심 기능 장애, 3등급은 일부 기능 저하, 4등급은 사용자 영향이 없는 내부 오류를 뜻한다. 1등급과 2등급은 즉시 온콜 담당자에게 자동 호출이 발송된다.

4. 롤백 기준
배포 후 10분 이내에 오류율이 기준치의 세 배를 넘으면 자동 롤백이 실행된다. 자동 롤백이 실패한 경우에는 수동으로 이전 버전 태그를 지정해 재배포한다. 데이터베이스 스키마 변경이 포함된 배포는 자동 롤백 대상에서 제외되므로, 사전에 역방향 마이그레이션 스크립트를 준비해 두어야 한다.

5. 사후 검토
2등급 이상 장애는 종료 후 3영업일 이내에 사후 검토 문서를 작성한다. 문서에는 발생 시각, 감지 경로, 조치 내역, 근본 원인, 재발 방지 대책을 포함한다. 책임 소재를 따지기보다 시스템과 절차의 개선점을 찾는 데 초점을 둔다.