API キーの管理

GPUStack は API キーによる認証に対応しています。各 GPUStack ユーザーは、自分の API キーを生成して管理できます。

API キーの作成

1. Access Control > API Keys ページに移動します。
2. Add API Key ボタンをクリックします。
3. API キーの Name と Description を入力し、Expiration を選択します。
4. API キーの Type を選択します。

• 自動生成：GPUStack が API キーを生成します。
• カスタム：Key フィールドに独自のキー値を入力します。カスタムを選んだ場合、このフィールドは必須です。覚える必要のないパスワードと同程度の強度を持つ値を選んでください。下の注意を参照してください。

5. Access Permissions 欄で、API キーの権限を選択します。

• プラットフォーム管理：ユーザー、モデル、Worker などのプラットフォーム管理エンドポイントへのアクセスを許可します。
• モデルアクセス：推論 API へのアクセスを許可します。選択した場合は、All models または Allowed models を選びます。Allowed models の場合は、この API キーでアクセスできるモデルを一覧から選択します。

権限を選択しなかった API キーには、アクセス権限がありません。 6. Save ボタンをクリックします。 7. キーをコピーして安全な場所に保存し、Done ボタンをクリックします。

アクセス権限の編集

1. Access Control > API Keys ページに移動します。
2. 編集する API キーを探します。
3. Operations 列の Edit ボタンをクリックします。
4. 必要に応じて Description を更新します。
5. Access Permissions 欄で、選択した権限を調整します。

• プラットフォーム管理：ユーザー、モデル、Worker などのプラットフォーム管理エンドポイントへのアクセスを許可します。
• モデルアクセス：推論 API へのアクセスを許可します。選択した場合は、All models または Allowed models を選びます。Allowed models の場合は、この API キーでアクセスできるモデルを一覧から選択します。

6. Save ボタンをクリックします。

API キーの削除

1. Access Control > API Keys ページに移動します。
2. 削除する API キーを探します。
3. Operations 列の Delete ボタンをクリックします。
4. 削除を確認します。

Server が利用できない間にキーを停止する

通常はキーを削除すれば十分です。Server が API ゲートウェイに通知し、数秒以内にそのキーが受け入れられなくなります。この節は、アップグレード中など、GPUStack Server が停止していて、キーを今すぐ停止する必要がある場合だけを対象とします。

ゲートウェイは、受け入れてよいキーのコピーを保持しているため、Server が利用できない間も推論を提供できます。そのコピーは Server 内ではなく Kubernetes にあるので、Server なしで編集できます。

1

kubectl -n higress-system edit wasmplugin gpustack-llm-ext-auth

spec.defaultConfig.local_auth の下からキーのエントリーを削除します。ほとんどの場合は keys にあり、キーのアクセスキーで索引付けされています。自動生成キーでは、gpustack_<access key>_<secret> の中央の部分です。カスタムキーの内部にはアクセスキーがないため、代わりに所有者の数値 user_id で keys を検索するか、exp 値をキーの有効期限と照合してください。

GPUSTACK_GATEWAY_AUTH_ALLOW_CUSTOM_KEYS が false の場合、カスタムキーは代わりに refs にあり、API に表示される数値のキー ID で索引付けされています。

どちらにも存在しないキーは、すでに各リクエストで Server に問い合わせています。そのため削除するものはなく、Server が復旧して削除を処理した時点で機能しなくなります。

変更は、このリソースの他の変更と同じ仕組みで伝わり、保存後数秒以内にゲートウェイへ到達します。すでに進行中のセッションにも適用されます。ゲートウェイが Server に問い合わせず受け入れるものは、先にこれらのエントリーと再照合されるため、1 つのエントリーを削除すると、すべての場所で同時に無効になります。

API キーの使用

GPUStack は API キーを Bearer トークンとして使用できます。

OpenAI 互換の GET /v1/models エンドポイントは、ユーザーと現在の組織コンテキストから見える、準備済みのモデルだけを返します。API キーを許可モデルに制限している場合、一覧は組織プレフィックス（team-a/qwen3 など）を含む、それらのモデル ID にさらに絞り込まれます。これは、従来の GET /v1-openai/models エンドポイントと、管理者が作成したキーにも適用されます。allowed_model_names 一覧が未設定または空の場合、追加のモデル制限は課されません。

curl を使用する例を次に示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

export GPUSTACK_API_KEY=your_api_key
curl http://your_gpustack_server_url/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{
    "model": "qwen3",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "stream": true
  }'