HTTP 엔드포인트

/admin* 라우트는 [server.admin]이 구성된 경우에만 존재합니다; 그 테이블이 없으면 하나도 등록되지 않습니다. 관리자 자격 증명은 구성된 헤더 또는 x-api-key로 받으며, read_keys 자격 증명은 위의 모든 GET을 통과하지만 모든 변경 작업에서는 403으로 거부됩니다. 로그인은 할 수 있습니다: POST /admin/login이 이를 받아들여 read 등급 세션을 발급하고, 그 세션의 변경 작업도 같은 403으로 거부됩니다. 이 로그인 POST에는 same-origin 가드가 걸려 있습니다: 교차 사이트 폼 제출은 자격 증명을 검사하기도 전에 403으로 거부되므로, 어떤 자격 증명 보유자도 이미 로그인한 운영자의 세션 쿠키를 자기 것으로 바꿔치기할 수 없습니다. 스크립트 로그인은 영향을 받지 않습니다 — Sec-Fetch-Site와 Origin이 모두 없으면 검사를 통과합니다. 다만 SPA 셸과 번들 파일은 예외로, GET /admin(두 표기 모두), GET /admin/{*path}, GET /admin/assets/{*path}는 관리자 인증 없이 제공됩니다. 이들은 운영자 데이터를 담지 않고, SPA가 읽는 값은 모두 요청마다 인증하는 /admin/api/* 뒤에 있으므로 안전합니다. 와일드카드 라우트 둘은 [server.admin]이 구성되고 --features ui로 빌드한 바이너리에서만 존재합니다. GET /admin/api/observed는 게이트웨이 호스트에서 지원되는 Claude Code, Codex CLI, Gemini CLI, Kimi Code, Grok CLI, Cursor.app 자격 증명을 자동으로 탐색하며, 그 소스를 갱신하거나 쓰지 않습니다. 그 탐색을 건너뛰려면 [server.admin].hide_observed를 설정하세요: 라우트는 여전히 인증을 거친 뒤 { "accounts": [] }를 반환하고, GET /admin/api/session은 hide_observed: true를 보고하며, 대시보드는 그 요청을 건너뛰고 관리형 풀 계정만 나열합니다.

관리자 SPA 번들(--features ui)

/admin/assets/{*path}와 /admin/{*path} SPA 폴백은 --features ui로 빌드한 바이너리에만 존재하며, 이 빌드는 ui/ 패키지에서 만든 번들을 바이너리에 내장합니다. 기본 cargo build는 Node 툴체인이 필요 없고 번들도 없으며 두 라우트 모두 등록하지 않습니다. 미리 빌드된 릴리스 바이너리는 이 기능을 켜고 빌드합니다.

폴백은 /admin 마운트 안으로 한정됩니다:

• /admin/ 아래에서 다른 라우트에 걸리지 않은 경로는 200과 text/html로 SPA 셸을 반환하므로, 클라이언트 측 딥링크가 새로고침에도 유지됩니다.
• /admin/api/ 아래에서 걸리지 않은 경로는 Anthropic 오류 형태의 404를 반환합니다 — 이 네임스페이스는 UI가 아니라 JSON이며, HTML로 답하면 클라이언트의 오류 처리가 깨집니다.
• 마운트 밖의 경로는 영향을 받지 않고 그대로 404입니다.

GET /admin도 셸이고, GET /admin/도 마찬가지입니다. 와일드카드 세그먼트는 빈 문자열에 매칭되지 않아 /admin/은 정확 일치 라우트에도 폴백에도 걸리지 않고 대시보드 자신의 루트에서 맨 404를 반환하게 되므로, 마운트 루트는 두 표기로 각각 등록합니다.

이 둘은 양쪽 빌드 모두에 등록되어 있으면서 응답이 피처에 따라 달라지는 관리자 경로로, 피처가 켜져 있으면 셸을, 꺼져 있으면 본문에 --features ui를 명시한 404를 반환합니다. 어느 쪽이든 등록해 두는 이유는 그 404가 해당 안내 문장을 담게 하기 위해서입니다 — 라우트를 아예 빼면 axum이 본문 없는 404를 돌려주고, 운영자는 그것을 [server.admin] 미설정과 구분할 수 없습니다.

관리자 경로 마이그레이션

호환성이 깨지는 변경입니다. 모든 관리자 JSON 라우트와 변경 라우트가 /admin/*에서 /admin/api/*로 이동했습니다. 이전 경로는 별칭으로 남지 않고 제거되어 이제 어떤 요청도 admin 핸들러에 도달하지 않습니다.

이전 경로에서 무엇이 돌아오는지는 빌드에 따라 다르므로, 그곳의 200을 성공으로 취급하면 안 됩니다:

• 기본 빌드 — 경로가 어디에도 등록되지 않아 404를 반환합니다.
• --features ui (미리 빌드된 릴리스 바이너리가 이쪽입니다) — GET은 마운트 하위의 다른 딥링크와 마찬가지로 /admin/{*path} SPA 폴백으로 넘어가 200 text/html 셸을 반환합니다. HEAD도 같습니다. 그 외 메서드는 Allow: GET,HEAD와 함께 405를 반환합니다 — 폴백이 any가 아니라 get으로 등록돼 있기 때문입니다.

따라서 이전 GET URL에 남아 있는 스크립트는 마이그레이션 신호가 아니라 HTML을 받습니다. /admin/api/*로 옮기세요. 응답의 Content-Type이 확실한 판별 기준입니다.

/admin은 대시보드 셸로 남고, /admin/login과 /admin/oidc/callback도 그대로입니다 — 이들은 API 라우트가 아니라 서버에서 렌더링되는 페이지입니다. 나머지는 모두 이동했으며, 이는 대시보드가 /admin/*을 탐색 가능한 딥 링크로 쓸 수 있게 하기 위해서입니다: 한 경로가 JSON 엔드포인트인 동시에 클라이언트 측 라우트일 수는 없으므로 호환용 별칭은 남기지 않았습니다.

스크립트로 호출하는 쪽은 기계적으로 한 번만 고치면 됩니다 — 경로에는 /admin 뒤에 /api 세그먼트 하나가 추가됩니다:

인증은 그대로입니다: 같은 관리자 자격 증명을 같은 헤더 또는 x-api-key로 보내며, 읽기/쓰기 등급도 동일합니다.

spend-limit 라우트는 부팅 시 [server.spend]가 구성된 경우에만 존재하며, [server.admin] 자격 증명으로 인증하므로 [server.gateway]와는 무관합니다. 자격 증명은 구성된 관리자 헤더(기본값 x-shunt-admin-token) 또는 x-api-key로 보냅니다 — 두 슬롯 모두 허용됩니다. 쓰기 자격 증명(write_keys 항목 또는 tokens_env/tokens_file 쌍)은 모든 작업을 사용할 수 있고, read_keys 자격 증명은 GET만 사용할 수 있으며 변경 작업에서는 403을 받습니다. POST는 user와 organization scope, daily/weekly/monthly period, user scope에서는 1–256바이트인 user_id, 1–19자리의 음수가 아닌 USD 센트 정수 문자열 또는 null인 amount를 받아 (scope, period) 기준으로 upsert합니다. 목록 페이지네이션은 limit(1–1000, 기본값 20), after_id, before_id, scope_type을 받으며 두 커서는 함께 사용할 수 없습니다. 모든 응답에는 request-id가 포함되고 오류는 Anthropic 오류 형태를 사용합니다. 제한과 변경 감사 레코드는 구성한 버전 JSON 상태 파일에 함께 저장되며, 각 변경은 admin-key:<id> 또는 admin-token:<name>으로 귀속됩니다 — 두 슬롯이 같은 등급의 서로 다른 자격 증명을 실은 경우 구성된 관리자 헤더 쪽이 귀속 대상입니다. GET /v1/organizations/spend_limits/effective(read 또는 write 자격 증명)는 주체·기간마다 한 행씩, 적용 상한(amount, source, spend_limit_id)과 미국 센트 단위 period_to_date_spend를 반환합니다. limit(1–1000, 기본값 20, 주체 수 기준), period[], user_ids[](최대 100개, 페이지네이션 없음), q, sort=spend_desc(period[]가 정확히 하나일 때), page를 받고 잘못된 입력에는 400 invalid_request_error로 응답합니다. period_to_date_spend는 meter가 읽을 수 있었던 카운터만 반영합니다. 저장된 카운터 레코드 복원에 실패한 주체는 unavailable 플래그가 풀릴 때까지 지출이 0이나 일부로만 보일 수 있으며, 로그의 복원 경고에 해당 주체가 기록됩니다. 제한은 /v1/messages와 인바운드 Codex 엔드포인트의 Responses 라우트 및 /alpha/search 별칭에 적용되며(상한을 넘은 Codex 턴은 429 usage_limit_reached를 받습니다. 인바운드 Codex 엔드포인트 참고), passthrough 또는 type = "noop" 라우트만으로 이루어진 체인에는 적용하지 않습니다. /audit은 노출하지 않습니다.

/user/bootstrap 라우트는 부팅 시 [server.gateway]가 활성화된 경우에만 존재하며 유효한 게이트웨이 bearer JWT를 요구합니다. static [server.auth] 토큰으로는 인증되지 않습니다. [server.gateway.desktop_bootstrap] 템플릿을 application/json으로 반환하며, 문자열 값 안의 ${user.email}, ${user.sub}, ${user.name}은 치환됩니다. 오류와 304를 포함한 모든 응답에 Cache-Control: no-store가 붙고, 라우트는 리다이렉트하지 않습니다.

policy가 없으면 로그인한 모든 사용자가 대상이고, policy가 있으면 policy의 match.emails에 포함되거나 catch-all policy(match 없음)가 있을 때 대상이 됩니다. 디바이스 코드 엔드포인트는 client_id가 없는 요청(Claude Desktop은 보내지 않습니다)과 client_id=claude-code 요청을 받으며, 다른 값은 거부합니다. client_id가 없는 요청에서 거부된 refresh 토큰은 400 {"error":"invalid_grant"}를 반환하고, claude-code 요청은 401을 유지합니다. Claude Desktop 연결을 참고하세요.

GET /managed/settings와 POST /v1/{metrics,logs,traces} 텔레메트리 ingest 라우트는 부팅 시 [server.gateway]가 활성화된 경우에만 존재하며, 둘 다 같은 게이트웨이 bearer JWT를 요구합니다. ingest 라우트는 관리형 Claude Code 클라이언트가 export하는 OTLP/HTTP 페이로드를 받아([server.gateway.telemetry]가 그 exporter들을 게이트웨이로 향하게 합니다) 요청 바이트를 해당 signal에 opt-in한 모든 목적지로 그대로 relay합니다. 인바운드 content-type과 content-encoding은 유지되고 목적지에 구성된 headers가 그 위에 적용됩니다(구성된 키는 전달값을 대체하며 헤더를 중복시키지 않습니다). 클라이언트의 Authorization 헤더는 전달되지 않고 relay는 리다이렉트를 따르지 않습니다. 목적지는 signal별로 opt-in하며(metrics 기본 on, logs/traces 기본 off), 어떤 목적지도 opt-in하지 않은 signal은 수신 후 폐기됩니다. relay는 분리되어 실행되므로 목적지 상태와 무관하게 응답은 항상 즉시 200이고, 성공 바디는 OTLP/HTTP에 따라 요청 프로토콜을 미러링합니다(application/json에는 {}, 그 외에는 빈 application/x-protobuf 바디). 32 MiB 인바운드 상한을 넘는 바디는 413을 받습니다.

인바운드 Codex Responses, 웹 검색, 모델 카탈로그, 분석 라우트는 [server.codex_endpoint]가 구성된 경우에만 존재합니다. Responses 라우트는 OpenAI Responses 요청과 응답을 HTTP/SSE(POST) 또는 WebSocket 업그레이드(GET)로 그대로 중계하며, [[server.codex_endpoint.routes]]로 모델별로 다른 Responses 호환 업스트림에 라우팅할 수도 있습니다. Codex 전용 두 모델 경로는 {"models":[]}을 반환하고, 공유 /v1/models는 쿼리에 client_version이 있을 때만 그 형태를 반환하며, 없으면 기존 Anthropic 계약을 유지합니다. 모든 카탈로그 변형은 일반 모델 탐색 인증 게이트를 사용합니다. 두 분석 라우트는 같은 인바운드 인증 정책을 적용하고, 클라이언트 payload를 전달하거나 보관하지 않으며, 인증 후에는 잘못된 JSON이나 초과 크기 본문에도 200 {}를 반환합니다. 정제된 이벤트 이름만 shunt.codex_client_events에 기록되며, 메트릭 sink가 없으면 순수 폐기 sink로 동작합니다. 세 웹 검색 경로는 Codex CLI의 내장 웹 검색을 Responses 경로와 같은 계정 풀과 인바운드 인증 정책으로 백엔드의 /codex/alpha/search에 그대로 중계합니다. POST만 받으며 [[server.codex_endpoint.routes]] 항목은 따르지 않습니다.

/usage 라우트는 [server.usage]가 구성된 경우에만 존재하며, [server.auth] 또는 [server.gateway]도 필요합니다. GET /v1/messages와 같은 클라이언트 토큰이나, Authorization: Bearer로 보낸 게이트웨이 로그인 액세스 토큰(shunt gateway claude로 시작한 세션이 보내는 값)으로 인증합니다. 유효한 게이트웨이 로그인은 [server.auth]를 거치지 않고 받아들이므로, [[server.auth.jwt]] 키 세트에 접근할 수 없어도 막히지 않습니다. 공유 계정 풀의 창별 잔여 여유(해당 창을 보고한 비활성 아님 계정들의 mean(clamp(cap - utilization, 0, 1)). cap은 그 창에 대해 계정에 적용되는 max_utilization 하드 캡이며 적용되는 캡이 없으면 1.0입니다. 즉 캡이 계정을 제외하기 전까지 풀 전체 용량 중 아직 쓸 수 있는 비율. 캡이 이미 해당 창의 요청에서 제외한 계정은 0으로 계산되며, 5h 또는 7d 캡은 Fable 요청에서도 그 계정을 제외합니다), 그 계정들이 보고한 리셋 시각 중 가장 이른 값(캡 때문에 0으로 계산되는 계정은 그 캡이 풀리는 시각 포함), ok/degraded/exhausted/capped 상태를 반환합니다. 계정 신원, 수, priority, disabled, 임계값, 계정별 수치는 공개하지 않습니다. 비활성 계정이 아닌 계정 중 해당 창을 보고한 계정이 하나도 없을 때만 null입니다. Codex 응답의 x-codex-* 헤더와 선택적인 wham/usage 폴링은 관측된 5시간 및 공유 주간 창을 채웁니다. WebSocket 전송에서는 스트림 안의 codex.rate_limits 이벤트가 재사용 연결을 포함한 모든 턴에서 같은 창을 채웁니다. Codex에는 Fable 범위(7d_oi) 신호가 없지만 혼합 프로바이더 풀에서는 다른 프로바이더가 집계 Fable 값을 제공할 수 있습니다. pool은 풀링되는 모든 프로바이더를 통틀은 집계이고, providers는 같은 정제된 집계를 풀링되는 프로바이더별로 구성된 프로바이더 이름을 키로 담으므로, 특정 프로바이더로 라우팅하는 클라이언트는 풀 전체 평균 대신 해당 프로바이더의 여유분과 상태를 읽을 수 있습니다. 풀링되지 않는 인증 모드의 프로바이더는 생략됩니다. 전체 응답 형태는 영문 엔드포인트 레퍼런스를 참고하세요. Claude Code 클라이언트라면 curl 없이도 읽을 수 있습니다. 이 저장소의 플러그인 마켓플레이스에 있는 shunt 모드가 /shunt:usage를 이 엔드포인트로 답하며, 창별 잔여 여유와 리셋 시각을 출력합니다. 함수 훅(CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1)이 필요하며 아직 얼리 액세스입니다.

풀 상태 capped는 사용 가능한 계정이 없고 활성화된(disabled가 아닌) 계정 중 일시 정지되지 않은 계정 하나 이상이 max_utilization* 하드 캡으로 제외되었음을 뜻하며([server.pool] 참고), exhausted와는 구분됩니다.

GET /와 GET /health는 [server.auth]가 활성화되어 있어도 열린 채로 유지되며(헬스체크 도구는 보통 토큰을 첨부할 수 없음) 민감한 것을 노출하지 않습니다 — 오직 상태, 버전, 그리고 이미 공개된 엔드포인트 목록만입니다. [[server.auth.jwt]] 항목을 구성하면 Authorization: Bearer의 검증된 외부 JWT가 클라이언트 토큰과 같은 게이팅 라우트를 인증합니다. 어떤 항목으로도 검증되지 않은 토큰은 401이고, 검증된 항목이 없으면서 토큰의 issuer와 일치하는 항목 중 캐시된 key set이 없는데 가져오기도 실패한 것이 있으면 503입니다.

게이트웨이 프로토콜

shunt는 공식 Claude Code LLM 게이트웨이 프로토콜을 구현합니다: 올바른 헤더 및 바디 필드 전달, 기능 패스스루, 시스템 프롬프트 어트리뷰션 처리. 게이트웨이 소유 오류는 Anthropic 오류 형태로 반환되고, 업스트림 컨텍스트 오버플로 오류는 Anthropic의 prompt is too long 표현으로 다시 쓰여 Claude Code의 압축-재시도가 발동하며, 스트리밍 응답은 버퍼링 없이 릴레이됩니다(선택적 keepalive ping 포함).