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

# 관리 API

> 관리 토큰으로 조직 잔액, 조직 API 키, 키 단위 사용량 및 과금 정보를 관리하고 조회합니다.

## 개요

Management API 는 일반 추론용 API 키를 쓰지 않고도 조직 잔액을 조회하고, 조직 API 키를 관리하며, 특정 키의 사용량과 과금을 조회할 수 있게 해줍니다.

Dashboard 의 **Settings** 페이지에서 관리 토큰을 사용하세요:

```bash theme={null}
Authorization: Bearer mt-your-management-token
```

<Warning>
  관리 토큰은 추론용 API 키와 다릅니다. `/v1/management/*` 에는 `mt-...` 를, `/v1/responses` 같은 모델 추론 엔드포인트에는 `sk-...` 를 사용하세요.
</Warning>

## 사용 가능한 엔드포인트

| Endpoint                                  | Method | 설명                            |
| ----------------------------------------- | ------ | ----------------------------- |
| `/v1/management/balance`                  | GET    | 현재 조직 잔액 합계 조회                |
| `/v1/management/api-keys`                 | GET    | 현재 조직에서 관리되는 사용자 API 키 목록 조회  |
| `/v1/management/api-keys`                 | POST   | 새 사용자 API 키 생성                |
| `/v1/management/api-keys/{keyId}`         | PATCH  | 이름, 사용 한도, 허용 모델, 만료, 상태 업데이트 |
| `/v1/management/api-keys/{keyId}/usage`   | GET    | 특정 키의 페이지네이션된 사용 상세 조회        |
| `/v1/management/api-keys/{keyId}/billing` | GET    | 특정 키의 집계 과금 내역 조회             |

## 사용 필터 계약

`GET /v1/management/api-keys/{keyId}/usage` 는 다음 query 파라미터를 지원합니다.

| 파라미터            | 타입      | 기본값 / 제한                   | 설명                                                                                                 |
| --------------- | ------- | -------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | 기본값 `1`, 최소 `1`            | 1부터 시작하는 페이지 번호                                                                                    |
| `limit`         | integer | 기본값 `50`, 최소 `1`, 최대 `100` | 페이지 크기                                                                                             |
| `model`         | string  | 최대 길이 `100`                | 호출자가 요청한 공개 모델 이름                                                                                  |
| `modelVendor`   | string  | 최대 길이 `100`                | 공개 모델 공급자                                                                                          |
| `scene`         | enum    | -                          | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                          | `platform` 또는 `byok`                                                                               |
| `startDate`     | string  | -                          | 포함 시작 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 를 지원합니다                                                |
| `endDate`       | string  | -                          | 포함 종료 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 를 지원합니다                                                |

`startDate` 와 `endDate` 를 함께 보내는 경우 `startDate` 는 `endDate` 보다 빠르거나 같아야 합니다.

## API 키 본문 계약

### POST /v1/management/api-keys

| 필드              | 타입             | 기본값 / 제한                         | 설명                                                                              |
| --------------- | -------------- | -------------------------------- | ------------------------------------------------------------------------------- |
| `name`          | string         | 필수, 기본값 `Default Key`, 길이 `1-50` | 표시 이름이며 서버에서 앞뒤 공백을 제거합니다                                                       |
| `limitAmount`   | number \| null | 최소 `0`, 입력 최대 `1000000`          | `null` 또는 생략 = 무제한, `0` = 0 한도. 양수는 저장된 상한으로 정규화되며 USD 환산 기준 `100000` 을 넘지 않습니다 |
| `limitCurrency` | enum           | default `USD`                    | USD만 지원됩니다. `CNY`를 보내면 `400 currency_retired`가 반환됩니다.                           |
| `models`        | string\[]      | 기본값 `[]`                         | 선택적 모델 허용 목록                                                                    |
| `expiresAt`     | string \| null | RFC3339 datetime                 | `null` 은 만료 없음 의미                                                               |

### PATCH /v1/management/api-keys/{keyId}

| 필드              | 타입             | 기본값 / 제한                | 설명                                                                        |
| --------------- | -------------- | ----------------------- | ------------------------------------------------------------------------- |
| `status`        | enum           | -                       | `active`, `inactive`, `revoked`                                           |
| `name`          | string         | 길이 `1-50`               | 업데이트된 표시 이름                                                               |
| `limitAmount`   | number \| null | 최소 `0`, 입력 최대 `1000000` | `null` = 무제한, `0` = 0 한도. 양수는 저장된 상한으로 정규화되며 USD 환산 기준 `100000` 을 넘지 않습니다 |
| `limitCurrency` | enum           | default `USD`           | USD만 지원됩니다. `CNY`를 보내면 `400 currency_retired`가 반환됩니다.                     |
| `models`        | string\[]      | -                       | 업데이트된 모델 허용 목록                                                            |
| `expiresAt`     | string \| null | RFC3339 datetime        | `null` 은 만료 제거                                                            |

PATCH 요청에는 최소 1개 이상의 필드가 포함되어야 합니다.

## 금액 계약

## 리포팅 의미

* `model` 은 호출자가 요청한 공개 모델을 의미합니다.
* `modelVendor` 는 숨겨진 호환 경로가 아니라 공개 모델 공급자를 의미합니다.
* `scene` 은 엔드포인트 또는 작업 유형에서 파생된 공개 요청 장면입니다.
* `accessChannel=platform` 은 해당 요청이 TokenLab 플랫폼 채널을 통해 과금되었음을 의미합니다.
* `accessChannel=byok` 은 해당 요청이 사용자의 업스트림 공급자 키를 사용했음을 의미합니다.

응답에는 공개 가능한 과금 및 리포팅 필드만 포함되며, 내부 라우팅 세부 정보와 물리 공급자 메타데이터는 숨겨집니다.

* `/usage` 개별 항목은 기본 요청의 정산이 완료되면 `billing_transaction_id` 를 포함할 수 있습니다. 요청 단위 대조에는 `request_id` 와 `billing_transaction_id` 를 함께 사용하세요.

## billing 페이지네이션 참고

`/usage` 는 페이지네이션됩니다. `/billing` 은 현재 집계형 엔드포인트이므로 `page` / `limit` 형태의 페이지네이션 메타데이터를 반환하지 않습니다. 행 단위 상세 기록이 필요하다면 `/usage` 를 사용하세요.

## 빠른 예시

먼저 현재 관리 토큰으로 조직 잔액을 확인하세요.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

이어서 같은 관리 토큰으로 조회 가능한 API 키 목록을 확인하세요.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/management/api-keys" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "key_abc123def456",
        "name": "Backend Worker",
        "key_prefix": "sk-abc123...",
        "status": "active",
        "limit_amount": 500.0,
        "limit_amount_decimal": "500",
        "used_amount": 148.25,
        "used_amount_decimal": "148.25",
        "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
        "expires_at": "2026-04-30T00:00:00.000Z",
        "last_used_at": "2026-03-27T08:12:45.000Z",
        "created_at": "2026-03-01T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>

## 다음 단계

* [조직 잔액 조회](/ko/api-reference/management/get-balance)
* [API 키 목록 조회](/ko/api-reference/management/list-api-keys)
* [API 키 생성](/ko/api-reference/management/create-api-key)
* [API 키 업데이트](/ko/api-reference/management/update-api-key)
* [API 키 사용량 조회](/ko/api-reference/management/get-api-key-usage)
* [API 키 과금 조회](/ko/api-reference/management/get-api-key-billing)