API 키 사용 가이드

이 문서는 LLM Gateway의 API를 사용하기 위한 인증 방식, 특히 API 키의 발급, 관리 및 사용 방법에 대해 설명합니다.

개요

LLM Gateway는 두 종류의 API 키를 사용하여 접근을 제어합니다.

관리자 키 (Admin Key):
- 헤더 이름: X-Admin-KEY
- 용도: API 클라이언트 키를 생성, 조회, 폐기하는 관리용 API를 호출할 때 사용됩니다.
- 특징: 시스템 관리자만 알고 있어야 하는 마스터 키입니다. 서버의 .env 파일에 ADMIN_API_KEY로 저장되어 있습니다.
클라이언트 키 (Client Key):
- 헤더 이름: X-API-KEY
- 용도: 모델 추론, 파일 다운로드 등 일반적인 모든 API 서비스를 호출할 때 사용됩니다.
- 특징: 관리자가 각 사용자 또는 서비스별로 발급해주는 고유한 키입니다.

1. 관리자 가이드

1.1. 새로운 클라이언트 키 발급하기

새로운 사용자나 서비스를 위해 신규 X-API-KEY를 발급합니다.

Endpoint: POST /manage/keys
요청 예시 (curl):

# 'my-first-client' 라는 이름으로 키를 발급하는 예시
# X-Admin-KEY 헤더에 자신의 관리자 키를 입력하세요.

curl -X POST http://localhost:8000/manage/keys \
-H "Content-Type: application/json" \
-H "X-Admin-KEY: <여기에_관리자_키를_입력하세요>" \
-d '{"client_name": "my-first-client"}'

성공 응답:

{
  "message": "API Key created successfully",
  "key_info": {
    "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_name": "my-first-client",
    "created_at": 1678886400,
    "is_active": "true"
  }
}

중요: 여기서 생성된 api_key 값을 사용자에게 전달해 주세요.

1.2. 발급된 모든 키 목록 조회하기

현재 시스템에 등록된 모든 클라이언트 키의 정보를 확인합니다.

Endpoint: GET /manage/keys
요청 예시 (curl):

curl -X GET http://localhost:8000/manage/keys \
-H "X-Admin-KEY: <여기에_관리자_키를_입력하세요>"

1.3. 클라이언트 키 폐기(삭제)하기

특정 클라이언트 키를 시스템에서 영구적으로 삭제하여 더 이상 사용할 수 없게 만듭니다.

Endpoint: DELETE /manage/keys/{api_key}
요청 예시 (curl):

# 폐기하려는 클라이언트 키를 URL 경로에 포함합니다.

curl -X DELETE http://localhost:8000/manage/keys/sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "X-Admin-KEY: <여기에_관리자_키를_입력하세요>"

2. 일반 사용자/클라이언트 가이드

관리자로부터 발급받은 X-API-KEY를 사용하여 LLM Gateway의 일반 API를 호출할 수 있습니다.

2.1. API 호출 방법

요구사항: 모든 요청의 HTTP 헤더에 X-API-KEY를 포함해야 합니다.
예시: 모델 목록 조회 API 호출

# 발급받은 자신의 클라이언트 키를 X-API-KEY 헤더에 입력하세요.

curl -X GET http://localhost:8000/api/v1/model/list \
-H "X-API-KEY: <여기에_발급받은_클라이언트_키를_입력하세요>"

인증 실패 시: 만약 키가 없거나 유효하지 않은 키를 사용하면, 401 Unauthorized 또는 403 Forbidden 오류가 발생합니다.

{
  "detail": "Invalid or missing API Key"
}

3.4 KiB Raw Blame History