Skip to Content
ReferenceCLIコマンドkey

key コマンド

keyコマンドは、KovaでAPI鍵を管理するためのコマンドです。API鍵を使用することで、AIエージェントがプログラマティックにウォレット操作を行えるようになります。

初回のエージェントキー発行は kova init が自動で行います。期限切れ後の再発行・置き換えには kova key rotate を使います。

構文

kova key <subcommand> [options]

サブコマンド一覧

サブコマンド説明
listAPI鍵一覧を表示（status フィールドで active / expiring_soon / expired / no_expiry を返す）
rotateAPI鍵をローテーション（新規作成 + 旧鍵 revoke + アクティブプロファイル credential 差し替え）

key list

作成済みのAPI鍵一覧を表示します。セキュリティ上の理由から、トークンは表示されません。

構文

kova key list

オプション

このサブコマンドにはオプションはありません。

使用例

kova key list

出力例:

{
  "ok": true,
  "data": {
    "keys": [
      {
        "id": "key-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "default",
        "wallet_ids": ["wallet-68cf6dba-a1b2-4c3d-8e9f-0123456789ab"],
        "policy_ids": [],
        "created_at": "2026-03-28T00:00:00.000Z",
        "expires_at": null,
        "status": "no_expiry"
      },
      {
        "id": "key-b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "agent-key",
        "wallet_ids": ["wallet-68cf6dba-a1b2-4c3d-8e9f-0123456789ab"],
        "policy_ids": ["policy-a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
        "created_at": "2026-03-27T00:00:00.000Z",
        "expires_at": "2026-06-25T00:00:00.000Z",
        "status": "active"
      }
    ]
  }
}

フィールドの意味は次のとおりです:

フィールド内容
idAPI 鍵 ID（rotate で内部的に参照される値）
name作成時に付けた表示名
wallet_idsこの鍵が利用できるアカウントの ID 配列
policy_idsこの鍵に適用される支払いポリシーの ID 配列（空配列ならポリシーなし）
created_at作成日時 (ISO 8601)
expires_at有効期限 (ISO 8601)。無期限の場合は null
status鍵の状態（次の表を参照）

status は次の 4 値を取ります:

status条件
active有効期限まで残り 14 日超
expiring_soon残り 14 日以内
expired既に expires_at を経過
no_expiryexpires_at が未設定（--expires never で作成）

API鍵が存在しない場合:

{
  "ok": true,
  "data": {
    "keys": []
  }
}

key rotate

API 鍵をローテーションします。新しい鍵を作成し、アクティブプロファイルの credential を新鍵に差し替えてから、古い鍵を無効化します。policy / wallet 関連付けは元の鍵から引き継がれます。

期限切れキーの再発行や、セキュリティ上の理由でキーを置き換えたい場合はこのサブコマンドを使います（旧来の「revoke して新規作成」という手順は kova key rotate 1 コマンドで置き換えられます）。

構文

kova key rotate --name <name> [--expires <duration>]

オプション

オプション必須/任意説明デフォルト
--name <name>必須ローテーション対象の API 鍵名-
--expires <duration>任意新しい鍵の有効期限（90d / 12w / ISO 8601 日付 / never）90d

使用例

kova key rotate --name agent-key --expires 90d

新しい鍵のトークンは stderr に 一度だけ 表示され、stdout には JSON 結果が返ります。

stderr:

New API key token (save this, shown only once):
  kova_NEW_TOKEN_VALUE...

stdout:

{
  "ok": true,
  "data": {
    "rotated": true,
    "oldKeyId": "key-old-...",
    "newKey": {
      "id": "key-new-...",
      "name": "agent-key",
      "expiresAt": "2026-08-13T00:00:00.000Z"
    }
  }
}

ローテーションの動作

  1. --name で指定された API 鍵を検索。
  2. 元の鍵に紐づくウォレットとポリシーを引き継いで新規鍵を作成。
  3. ポリシーが紐づいていればハッシュを記録（失敗時は新鍵を無効化して中途半端な状態を防止）。
  4. アクティブプロファイルの credential / apiKeyId を新鍵に差し替え。
  5. 旧鍵を OWS から無効化。
  6. 旧鍵分のローカルハッシュ記録を best-effort で削除（失敗時は warning として返す）。

重要な注意点

  1. トークン表示は一度だけ: stderr に出る新鍵トークンは保存し忘れると取り戻せません。
  2. 同名鍵の前提: --name で一意に特定できる必要があります。同名鍵が複数存在する場合は最初に見つかった鍵が rotate 対象になります。
  3. ポリシー hash の原子性: hash 記録に失敗すると新鍵は無効化され、credential も差し替えられません（旧鍵は無傷）。
  4. 無効化は OWS 側のみ: 旧鍵は OWS から削除されますが、shell 環境変数等にコピーされたトークンは利用者側で破棄してください。

よくあるエラーと対処法

WALLET_NOT_FOUND

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "Wallet 'unknown-wallet' not found."
  }
}

対処法:

  • kova wallet info でウォレットの状態を確認する
  • ウォレットが存在しない場合は、kova init で作成する

INVALID_PARAMS

エラーメッセージ（無効なポリシーID）:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Policy 'invalid-policy-id' not found."
  }
}

対処法:

  • kova policy listでポリシーIDを確認する
  • ポリシーIDのスペルミスを確認する

エラーメッセージ（鍵が見つからない）:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "API key 'unknown-key' not found."
  }
}

対処法:

  • kova key listでAPI鍵名を確認する
  • API鍵名のスペルミスを確認する

OWS_ERROR

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "OWS_ERROR",
    "message": "Failed to create API key: Internal error."
  }
}

対処法:

  • ウォレットファイルの整合性を確認する（kova wallet info）
  • Kovaを再起動してみる
  • ディスク容量を確認する

API鍵の使用方法

環境変数の設定

生成されたAPI鍵を環境変数に設定します:

export KOVA_API_KEY=kova_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12

ポリシー制約の検証

ポリシーが適用されたAPI鍵では、以下の制約が適用されます:

  1. maxAmount: 指定金額を超える送金はエラー
  2. allowedChains: 許可されていないチェーンへの操作はエラー
  3. allowedTokens: 許可されていないトークンの操作はエラー
  4. requireApproval: すべての操作に人間の承認が必要

ポリシー違反の例:

{
  "ok": false,
  "error": {
    "code": "POLICY_DENIED",
    "message": "Amount 100 USDC exceeds policy limit of 10 USDC."
  }
}

セキュリティのベストプラクティス

定期的なローテーション

--expires 90d がデフォルトなので、有効期限切れの前に key rotate を実行する運用が想定されています。

kova key rotate --name agent-key --expires 90d

新しい鍵のトークンが stderr に表示され、アクティブプロファイルの credential が自動的に差し替わります。

本番環境

  1. 必ずポリシーを適用: ポリシーなしのAPI鍵は使用しない
  2. 承認を必須化: requireApproval: trueを設定
  3. 最小権限の原則: 必要最小限の金額・チェーン・トークンのみ許可
  4. 定期的な監査: kova key listで未使用のAPI鍵を確認し、必要に応じてローテーション

関連コマンド

  • policy - API鍵に適用するポリシーを作成
  • wallet - API鍵に関連付けるウォレットを確認
  • config - デフォルトウォレットを設定
  • send - API鍵を使って送金

次のステップ

  • API鍵の期限が切れたら: kova key rotate --name <name> で再発行しましょう
  • ポリシー適用: policyでAPI鍵に適用するポリシーを作成しましょう
  • セキュリティ: セキュリティガイドでAPI鍵の安全な管理方法を確認しましょう
Last updated on
policylaunch