인증

추론 키와 관리 키는 서로 다른 키다

/api/v1 은 Authorization: Bearer <키> 헤더 하나로만 인증합니다. 쿠키도, 쿼리 파라미터도, api_key 본문 필드도 받지 않습니다.

Authorization: Bearer sk-mo-v1-3f2a…

키 두 종류

접두사	종류	할 수 있는 일
`sk-mo-v1-`	추론 키	모델 호출, 자기 사용량·잔액 조회
`sk-mo-mgmt-v1-`	관리 키	추론 키를 발급·조회·수정·폐기

키는 <접두사> + 랜덤 32바이트의 hex 64자입니다. 서버에는 평문이 남지 않고 sha256(평문 전체) 와 표시용 마스킹 문자열(sk-mo-v1-3f2…a19)만 저장됩니다. 발급 화면을 벗어나면 평문을 다시 볼 수 없습니다.

어떤 경로에 어떤 키가 필요한가

경로	필요한 키
`POST /chat/completions`, `POST /completions`	추론 키
`GET /models/user`	추론 키
`GET /generation`, `GET /key`, `GET /auth/key`, `GET /credits`	추론 키 또는 관리 키
`GET/POST /keys`, `GET/PATCH/DELETE /keys/{hash}`	관리 키만
`GET /models`, `/models/count`, `/models/{author}/{slug}/endpoints`, `/providers`, `/datasets/*`, `/benchmarks`	없음

/key·/credits 처럼 "이 키가 살아 있는가"를 확인하는 경로는 두 종류 다 받습니다. SDK 의 헬스체크 호출을 종류 때문에 막을 이유가 없기 때문입니다. 반대로 다른 키를 만들고 지우는 /keys 는 관리 키만 받습니다.

관리 키를 왜 따로 두는가

/api/v1 은 SDK 표면입니다. 여기에 브라우저 세션 쿠키 인증을 섞으면 CSRF 표면이 열립니다. 그래서 대시보드 UI 는 /api/v1/keys 를 쓰지 않고 세션 쿠키로 인증하는 별도 대시보드 API 를 쓰고, /api/v1 은 쿠키를 아예 보지 않습니다. 두 경로는 내부적으로 같은 서비스 함수를 부르므로 키의 수명주기 규칙은 한 벌입니다.

관리 키는 대시보드 설정 화면에서 직접 발급합니다. 관리 API 키를 보세요.

키가 거절되는 경우

검증 순서는 아래 표 그대로입니다. 순서가 결과를 바꿉니다 — 정지 상태를 만료보다 먼저 보기 때문에, 만료된 정지 키는 401 이 아니라 402/403 을 받습니다. "충전하면 풀리는가"라는 실제 질문에 먼저 답하는 쪽을 골랐습니다.

순서	상태	응답
1	해시가 DB 에 없음	401 `invalid_api_key`
2	`disabled` 이거나 폐기됨	401 `invalid_api_key`
3	잔액 부족으로 시스템이 정지	402 `insufficient_credits` (`metadata.balance_krw` 동봉)
4	관리자가 정지	403 `key_suspended`
5	`expires_at` 이 지남	401 `expired_api_key`
6	키 종류가 경로와 다름	401 `invalid_api_key`

403 key_suspended 는 402 와 구분해서 씁니다. 402 는 충전하면 풀리고, 403 은 충전해도 풀리지 않습니다. 코드만 보고도 다음 행동이 갈리도록 나눈 것입니다.

Authorization 헤더가 아예 없거나 Bearer 형식이 아니면 역시 401 invalid_api_key 입니다.

확인해 보기

curl https://openrouter.myip.co.kr/api/v1/key \
  -H "Authorization: Bearer $MYIP_API_KEY"

성공하면 이런 본문이 옵니다. 금액은 전부 원(₩)입니다.

json

{
  "data": {
    "label": "sk-mo-v1-3f2…a19",
    "name": "production",
    "limit": 100000,
    "usage": 25500,
    "limit_remaining": 74500,
    "limit_reset": "monthly",
    "is_management_key": false,
    "usage_daily": 1200,
    "usage_weekly": 9000,
    "usage_monthly": 25500
  }
}

전체 필드는 GET /key에 있습니다.

키를 안전하게 다루기

키를 브라우저 번들이나 모바일 앱에 넣지 마세요. 서버에서 프록시하세요.
환경변수로 주입하세요. 이 문서의 예제는 전부 MYIP_API_KEY 를 씁니다.
용도별로 키를 나누고 각 키에 사용 한도(limit)를 거세요. 한도를 넘기면 그 키만 402 key_limit_exceeded 로 멈춥니다(요청 한도).
새 나갔다고 판단되면 폐기하세요. 폐기는 영구입니다 — 되돌릴 수 없고, 되돌리는 API 도 없습니다.

마지막 수정 2026. 9. 5.