> ## 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/ を使い、クォータ・有効期限・利用モデルの許可リストを付けたAPIキーの発行と、キーの表示・更新・無効化・削除をコードから実行できます。

コンソールのトークン画面でできる操作を、自分のコードから実行できます。取引先ごとの上限付きキーの自動発行や、案件終了時のキーの一括無効化に向いています。これらのキーでの呼び出しは、お客様の残高から課金されます。

| 項目 | 内容 |
| - | - |
| エンドポイントのプレフィックス | `https://api.laozhang.ai/api/token/` |
| 認証 | アカウントのAccessToken。取得方法は[残高照会API](https://docs.laozhang.ai/ja/api-capabilities/balance-query.md)を参照 |
| クォータ | 500,000クォータ = 1米ドル |
| レスポンスの形式 | `{"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` |
| キーを1件取得 | `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}` |

一覧と検索は1ページ10件で、`p` は0から始まります。これらの結果の `key` はマスクされています。モデルの呼び出しに使う完全なキーは、表示用のエンドポイントで取得してください。

## 新しいキーのフィールド

| フィールド | 型 | 説明 |
| - | - | - |
| `name` | string | キーの名前。検索に使います。長すぎる名前は拒否されます |
| `remain_quota` | integer | クォータ単位の利用上限。`500000` が1米ドルです |
| `unlimited_quota` | boolean | `true` にすると上限がなくなり、`remain_quota` は無視されます |
| `expired_time` | integer | 有効期限（Unix秒）。`-1` は無期限です |
| `group` | string | トークングループ。通常は `default` です。ほかのグループは[課金と料金](https://docs.laozhang.ai/ja/pricing.md)に一覧があります |
| `billing_type` | integer | 課金方式。`4` が従量優先（推奨）、`1` が従量課金、`2` が回数課金です |
| `models` | string | 利用を許可するモデルIDをカンマ区切りで指定します。空文字列ならすべてのモデルを許可します |
| `remark` | string | 任意のメモ |

`billing_type` によって、そのキーで呼び出せるモデルが決まります。従量課金のキーは従量課金のモデルだけ、回数課金のキーは回数課金のモデルだけ、従量優先のキーは両方を呼び出せます。3つの方式は[課金と料金](https://docs.laozhang.ai/ja/pricing.md)で説明しています。

## キーの作成と表示

次のスクリプトは、上限5米ドル、有効期限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 trial",
})
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米ドル分を追加
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/ja/api-capabilities/log-query.md)を使ってください。

### `model_limits` を設定したのに無視されるのはなぜですか？

モデルの許可リストは `models` からのみ読み取られます。許可するモデルIDをカンマ区切りの文字列にして、`models` に指定してください。

## 関連ドキュメント

* AccessTokenの取得と残高の確認：[残高照会API](https://docs.laozhang.ai/ja/api-capabilities/balance-query.md)
* キーごとの呼び出し記録のエクスポート：[ログ照会API](https://docs.laozhang.ai/ja/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.