> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 토큰 관리 API: 코드로 API 키 발급·관리

> /api/token/으로 quota, 만료일, 모델 허용 목록을 지정한 API 키를 발급하고 전체 키 조회, 수정, 비활성화, 삭제까지 처리합니다.

토큰 관리 API는 콘솔의 토큰 페이지에서 하는 작업을 코드로 처리합니다. 하위 고객마다 한도가 있는 키를 자동으로 발급하거나, 프로젝트가 끝났을 때 키를 한꺼번에 비활성화하는 데 쓸 수 있습니다. 이 키로 한 호출은 내 계정 잔액에서 차감됩니다.

| 항목 | 내용 |
| - | - |
| 엔드포인트 접두사 | `https://api.laozhang.ai/api/token/` |
| 인증 | 계정 AccessToken. [AccessToken 발급](https://docs.laozhang.ai/ko/api-capabilities/balance-query.md) 참고 |
| Quota | 500,000 quota = 1 USD |
| 응답 형식 | `{"success": true, "message": "", "data": ...}` |

> [!WARNING]
>
> **AccessToken은 계정을 전부 제어할 수 있으므로 서버에만 보관하세요.**
>
> * 브라우저나 앱에 넣거나 고객에게 전달하지 마세요. 고객에게는 직접 만든 API 키만 줍니다.
> * 잘못된 토큰도 HTTP 200과 `success: false`로 응답하므로 호출할 때마다 `success`를 확인하세요.

## 엔드포인트

| 작업 | 요청 |
| - | - |
| 키 목록 | `GET /api/token/?p=0` |
| 이름으로 검색 | `GET /api/token/search?keyword=NAME&p=0` |
| 키 하나 조회 | `GET /api/token/{id}` |
| 키 생성 | `POST /api/token/` |
| 전체 키 확인 | `POST /api/token/{id}/key` |
| 키 수정 | `PUT /api/token/` |
| 활성화 또는 비활성화 | `PUT /api/token/?status_only=true` |
| 키 삭제 | `DELETE /api/token/{id}` |

목록과 검색은 페이지당 키 10개를 반환하며 `p`는 0부터 시작합니다. 이 결과의 `key`는 일부가 가려져 있으므로, 모델 호출에 쓸 전체 키는 키 확인 엔드포인트로 가져옵니다.

## 새 키의 필드

| 필드 | 타입 | 설명 |
| - | - | - |
| `name` | string | 키 이름. 검색에 쓰이며 너무 길면 거부됨 |
| `remain_quota` | integer | quota 단위의 사용 한도. `500000`이 1 USD |
| `unlimited_quota` | boolean | `true`이면 한도가 없으며 `remain_quota`는 무시됨 |
| `expired_time` | integer | Unix 초 단위 만료 시각. `-1`은 만료 없음 |
| `group` | string | 토큰 그룹. 보통 `default`이며 다른 그룹은 [과금과 가격](https://docs.laozhang.ai/ko/pricing.md)에 정리되어 있음 |
| `billing_type` | integer | 과금 방식. `4` 사용량 우선(권장), `1` 사용량 과금, `2` 건당 과금 |
| `models` | string | 쉼표로 구분한 모델 ID 허용 목록. 빈 문자열이면 모든 모델 허용 |
| `remark` | string | 선택 사항인 메모 |

`billing_type`은 키가 호출할 수 있는 모델을 정합니다. 사용량 과금 키는 사용량 과금 모델만, 건당 과금 키는 건당 과금 모델만, 사용량 우선 키는 둘 다 호출합니다. 세 방식은 [과금과 가격](https://docs.laozhang.ai/ko/pricing.md)에서 설명합니다.

## 키 생성과 전체 키 확인

아래 스크립트는 한도 5 USD, 만료 30일, 허용 모델 2개인 키를 만든 뒤 전체 키를 확인합니다. `requests`가 필요합니다(`python -m pip install requests`).

```python theme={null}
import os
import time

import requests

BASE = "https://api.laozhang.ai"
HEADERS = {"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]}


def call(method, path, **kwargs):
    response = requests.request(method, BASE + path, headers=HEADERS, timeout=30, **kwargs)
    response.raise_for_status()
    payload = response.json()
    if not payload.get("success"):
        raise RuntimeError(f"{path}: {payload.get('message')}")
    return payload.get("data")


created = call("POST", "/api/token/", json={
    "name": "customer-acme",
    "remain_quota": 5 * 500_000,
    "unlimited_quota": False,
    "expired_time": int(time.time()) + 30 * 86400,
    "group": "default",
    "billing_type": 4,
    "models": "gpt-5.4-mini,gemini-3.8-flash",
    "remark": "Acme 체험용",
})
token_id = created["id"]

key = call("POST", f"/api/token/{token_id}/key")["key"]
print(token_id, key[:6] + "...")
```

확인한 키는 `sk-` 접두사 유무와 관계없이 모델 API 키(`Authorization: Bearer <key>`)로 쓸 수 있습니다. 전달하기 전에 시크릿 매니저에 저장하세요. 키 확인 엔드포인트는 호출 제한이 엄격하므로 반복 호출하지 마세요.

## 수정, 비활성화, 삭제

수정은 키 객체 전체를 교체합니다. `GET /api/token/{id}`로 읽어 와서 필요한 필드만 바꾼 뒤 전체 객체를 `PUT`으로 다시 보내세요. 일부 필드만 보내면 나머지가 초기화될 수 있습니다.

```python theme={null}
token = call("GET", f"/api/token/{token_id}")
token.pop("key", None)
token["remain_quota"] += 10 * 500_000   # 10 USD 추가
token["models"] = "gpt-5.4-mini,gemini-3.8-flash,deepseek-v4-flash"
call("PUT", "/api/token/", json=token)

call("PUT", "/api/token/?status_only=true", json={"id": token_id, "status": 2})  # 비활성화
call("PUT", "/api/token/?status_only=true", json={"id": token_id, "status": 1})  # 다시 활성화

call("DELETE", f"/api/token/{token_id}")
```

변경은 즉시 적용됩니다.

* 비활성화했거나 삭제한 키로 모델을 호출하면 HTTP 401 `Invalid token.`이 반환됩니다.
* 허용 목록에 없는 모델을 호출하면 해당 토큰이 그 모델을 쓸 수 없다는 메시지와 함께 HTTP 403이 반환됩니다.

## 오류

| 증상 | 원인과 해결 |
| - | - |
| HTTP 401과 `AUTH_REQUIRED` | `Authorization` 헤더가 없음 |
| HTTP 200, `success: false`, "access token is invalid" | AccessToken이 틀렸거나 다시 발급되었음 |
| HTTP 403과 "does not have write permission" | 읽기 전용 토큰이라 키를 만들거나 수정, 삭제할 수 없음 |
| `success: false`와 이름이 너무 길다는 메시지 | `name`을 줄이세요 |
| `GET /api/token/{id}`가 "record not found" 반환 | 키가 삭제되었거나 다른 계정의 키임 |

## 자주 묻는 질문

### 고객의 키는 누구의 잔액으로 결제되나요?

내 잔액입니다. 키마다 `remain_quota`를 지출 한도로 설정하세요. 키가 한도에 도달하면 작동을 멈추며 내 나머지 잔액을 끌어 쓰지 않습니다.

### 키별 사용량은 어떻게 보나요?

목록과 상세 응답의 `used_quota`가 해당 키의 누적 사용량입니다. 시간대나 모델별로 나누어 보려면 `token_name`을 지정한 [로그 조회 API](https://docs.laozhang.ai/ko/api-capabilities/log-query.md)를 사용하세요.

### `model_limits`를 설정했는데 왜 무시되나요?

모델 허용 목록은 `models`에서만 읽습니다. 허용할 모델 ID를 쉼표로 구분한 문자열로 `models`에 넣으세요.

## 관련 문서

* AccessToken 발급과 잔액 확인: [잔액 조회 API](https://docs.laozhang.ai/ko/api-capabilities/balance-query.md)
* 키별 호출 기록 내보내기: [로그 조회 API](https://docs.laozhang.ai/ko/api-capabilities/log-query.md)
* 콘솔에서 키를 만들고 IP 허용 목록을 설정하기: [API 키 생성, 보관, 교체, 폐기](https://docs.laozhang.ai/en/faq/token-management.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.