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

# 認証とクォータ

> System APIのリクエストを認証し、アカウントとAPIキーのクォータ単位を換算します。

## 概要

System APIは、APIキー、スマートルーティングキー、およびウォレット操作など、MixRouteアカウント内のリソースを管理します。モデル推論APIとは別のAPIです。

| 目的 | ベースURL | 認証情報 |
| - | - | - |
| アカウントとキーの管理 | `https://api.mixroute.ai` | システムアクセストークン |
| モデル推論 | `https://api.mixroute.ai/v1` | `sk-`で始まるAPIキー |

<Warning>
  システムアクセストークンは、アカウント単位の管理アクセス権を付与します。ブラウザーのコード、モバイルアプリケーション、ログ、ソース管理には絶対に含めないでください。
</Warning>

## システムアクセストークンの取得

[MixRouteコンソール](https://console.mixroute.ai/settings)で**アカウント設定 → APIアクセス**を開き、システムアクセストークンを生成してコピーしてください。トークンはシークレットマネージャーに保存してください。

<Warning>
  `GET /api/user/token`は、新しいシステムアクセストークンを生成します。これは読み取り操作ではなくローテーション操作であり、以前のトークンを無効にします。通常の自動処理では呼び出さないでください。
</Warning>

例で使用する値を設定してください。

```bash theme={null}
export BASE_URL="https://api.mixroute.ai"
export ACCESS_TOKEN="YOUR_SYSTEM_ACCESS_TOKEN"
export USER_ID="YOUR_NUMERIC_USER_ID"
```

数値のユーザーIDは、アカウント設定ページに表示されます。

## 認証ヘッダー

認証が必要なすべてのSystem APIリクエストには、両方のヘッダーが必要です。

```http theme={null}
Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN
New-Api-User: YOUR_NUMERIC_USER_ID
```

JSONボディを含むリクエストでは、次のヘッダーも送信してください。

```http theme={null}
Content-Type: application/json
```

ユーザーIDは、システムアクセストークンに属している必要があります。認証失敗時のHTTPステータスコードは1つに統一されていません。認証情報の欠落やユーザーIDの不一致ではHTTP `401`が返される場合があり、無効なアクセストークンでは現在、`success: false`を伴うHTTP `200`が返されます。HTTPステータスとレスポンスエンベロープの両方を必ず確認してください。

アカウントデータを変更せずに認証を確認するには、このリクエストを使用してください。

```bash theme={null}
curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -e '
      if .success == true then .data
      else error(.message // "authentication failed")
      end
    '
```

## レスポンスエンベロープ

大半のシステムAPIエンドポイントは、このエンベロープを使用します。

```json theme={null}
{
  "success": true,
  "message": "",
  "data": {}
}
```

一部の検証エラーや認証失敗では、`success: false`を伴うHTTP `200`が返されるため、HTTPのステータスと`success`フィールドの両方を確認してください。

```bash theme={null}
response=$(curl -fsS "$BASE_URL/api/user/self/groups" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

jq -e '.success == true' <<< "$response" >/dev/null || {
  jq -r '.message // "System API request failed"' <<< "$response" >&2
  exit 1
}
```

## クォータの単位

アカウントのクォータとAPIキーのクォータは、米ドルそのものではなく、内部クォータ単位で保存されます。現在の換算値は、公開ステータスエンドポイントから取得してください。

```bash theme={null}
quota_per_unit=$(curl -fsS "$BASE_URL/api/status" \
  | jq -er '.data.quota_per_unit')

usd_amount=20
internal_quota=$((usd_amount * quota_per_unit))
printf 'Quota for $%s: %s\n' "$usd_amount" "$internal_quota"
```

以下の式を使用します。

```text theme={null}
internal quota = USD amount × quota_per_unit
USD amount     = internal quota ÷ quota_per_unit
```

<Note>
  `quota_per_unit`はデプロイ設定であり、変更される可能性があります。現在の値をハードコードせず、取得して使用してください。
</Note>

### アカウント残高とキーのクォータの違い

* アカウント残高（`GET /api/user/self`、フィールド`quota`）は、そのアカウントで利用できるウォレット残高です。
* キークォータ（`remain_quota`）は、1つのAPIキーの利用額の上限です。
* キーにクォータを割り当てても、ウォレットから資金が移動することはありません。
* `unlimited_quota: true`はキー単位の上限を解除しますが、リクエストは引き続きアカウント残高を消費します。

現在のアカウント残高を取得して表示します。

```bash theme={null}
user=$(curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

quota_per_unit=$(curl -fsS "$BASE_URL/api/status" \
  | jq -er '.data.quota_per_unit')

jq --argjson unit "$quota_per_unit" '{
  user_id: .data.id,
  internal_quota: .data.quota,
  balance_usd: (.data.quota / $unit)
}' <<< "$user"
```

## 利用可能なグループ

キーを作成する際は、アカウント固有のグループ一覧を使用してください。

```bash theme={null}
curl -fsS "$BASE_URL/api/user/self/groups" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq '.data'
```

別のアカウントで利用できるグループが、自分のアカウントでも利用できるとは限りません。`default`グループは、このガイドの大半の例に適しています。

## セキュリティチェックリスト

* システムアクセストークンはサーバー側で保持してください。
* 自動化には専用のアカウントまたはトークンを使用してください。
* キーの表示用エンドポイントのレスポンスを、決してログに記録しないでください。
* 可能な限り、各APIキーに分かりやすい名前、有効期限、クォータ、IP制限を設定してください。
* キーをローテーションする際は、まず代わりのキーを作成し、トラフィックの移行後に古いキーを無効化して削除してください。


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