# API 키 사용 가이드

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

## 개요

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

1.  **관리자 키 (Admin Key):**
    -   **헤더 이름:** `X-Admin-KEY`
    -   **용도:** API 클라이언트 키를 생성, 조회, 폐기하는 관리용 API를 호출할 때 사용됩니다.
    -   **특징:** 시스템 관리자만 알고 있어야 하는 마스터 키입니다. 서버의 `.env` 파일에 `ADMIN_API_KEY`로 저장되어 있습니다.

2.  **클라이언트 키 (Client Key):**
    -   **헤더 이름:** `X-API-KEY`
    -   **용도:** 모델 추론, 파일 다운로드 등 일반적인 모든 API 서비스를 호출할 때 사용됩니다.
    -   **특징:** 관리자가 각 사용자 또는 서비스별로 발급해주는 고유한 키입니다.

---

## 1. 관리자 가이드

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

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

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

```bash
# '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"}'
```

- **성공 응답:**
```json
{
  "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`):**

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

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

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

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

```bash
# 폐기하려는 클라이언트 키를 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 호출**

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

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

- **인증 실패 시:**
만약 키가 없거나 유효하지 않은 키를 사용하면, `401 Unauthorized` 또는 `403 Forbidden` 오류가 발생합니다.
```json
{
  "detail": "Invalid or missing API Key"
}
```