API Overview
SnowPass REST API 3계층 — private / public / admin
SnowPass 의 REST API 는 역할이 다른 3계층으로 나뉜다. 모든 엔드포인트의 상세 스펙은 좌측 목록에서 확인한다 (OpenAPI 3.0 스펙에서 자동 생성).
| 계층 | Prefix | 인증 | 호출 주체 |
|---|---|---|---|
| Private API | /v1 | X-Api-Secret (sk_*) | RP 백엔드 (server-to-server) — Java Client Library 가 래핑 |
| Public API | /p1 | X-Api-Key (pk_*) + ceremony token | 브라우저 — JS SDK 가 래핑 |
| Admin API | /admin/api | 세션 쿠키 | SnowPass Admin Console |
| JWKS | /.well-known/jwks.json | 없음 (공개) | result token 오프라인 검증 |
Ceremony 토큰 흐름
private API 로 발급한 ceremony token (sprt_*/spat_*) 을 브라우저에 내려주면, 브라우저가
public API 로 ceremony 를 수행하고 result token (JWT) 을 돌려받는다. result token 은 다시
private API /v1/auth/verify 로 검증한다 (jti 1회용). 자세한 흐름은
Sequence Diagrams 참고.
Error Format
모든 오류 응답은 아래 형식을 따른다. 코드 목록은 Error Codes 참고.
{ "error": { "code": "USER_LOCKED", "message": "..." } }