JEDI 거버넌스 게이트웨이 — 클라이언트 API 백서 v1
1. 개요
JEDI 거버넌스는 모든 AI 접근이 게이트웨이(L1)를 통과하도록 강제합니다. 클라이언트는 개인 API 키로 모델을 직접 호출해서는 안 되며(Shadow AI 차단), 반드시 아래 정의된 게이트웨이 API를 통해서만 접근합니다.
2. 인증 흐름
- 사용자는 사내 SSO(OIDC/SAML)로 로그인합니다.
- 클라이언트는 SSO ID 토큰을
/v1/auth/exchange에 전달해 **단기 JWT 액세스 토큰(15분)**과 Refresh Token을 발급받습니다.
- 모든 API 호출 시
Authorization: Bearer <JWT> 헤더를 포함합니다.
3. 엔드포인트 개요
| 엔드포인트 | 메서드 | 용도 |
|---|
/v1/auth/exchange | POST | SSO 토큰 → JWT 교환 |
/v1/agent/invoke | POST | AI 작업 요청 제출 (핵심 엔드포인트) |
/v1/agent/invoke/{request_id} | GET | 비동기 요청 상태 조회 |
/v1/approval/{approval_id} | GET | 승인 대기 항목 상세 조회 |
/v1/approval/{approval_id}/decision | POST | 승인/반려 결정 제출 |
/v1/usage/session/{session_id} | GET | 세션 단위 비용·토큰 사용량 조회 |
/v1/webhooks | POST | 웹훅 콜백 등록 |
/health | GET | 게이트웨이 헬스체크 |
4. 에러 코드 & 클라이언트 처리
| 코드 | 의미 | 클라이언트 처리 |
|---|
| 401 | 인증 토큰 만료/무효 | Refresh Token으로 재발급 시도 |
| 403 | 정책상 권한 없음 | 재시도 금지. 사용자에게 안내 |
| 409 | 중복 요청 | 기존 request_id로 상태 조회 |
| 422 | DLP 위반 (민감정보) | 마스킹 안내 표시, 원문 재전송 금지 |
| 429 | 세션/부서 비용 쿼터 초과 | Retry-After 헤더 적용 지수 백오프 |
| 503 | 게이트웨이 장애 | 자동 재시도 (최대 3회, 백오프) |