メインコンテンツへスキップ
API キーを作り、expl に渡し、安全に扱います。CI、スクリプトなど、ブラウザのない場所で使います。

API キーとは

API キーは、プログラムが、あなたとして Exploratory を読むための文字列です。パスワードの代わりに使います。CI(変更のたびに自動で処理を流す仕組み)では、人がブラウザでサインインできないので、API キーを渡します。キーは exp_pat_ で始まります。 キーで読めるのは、ブラウザでのサインインと同じ、あなたが見られる内容です(読み取りのみ)。作成や変更はできません。キーを作れるのは Author だけです。 このページのコマンドは token(expl server token)という名前ですが、扱うものは API キーです。

API キーを作る

1. API キーを開く

exploratory.io の右上のアイコンから「アカウント設定」を開き(https://exploratory.io/account/settings )、「API キー」の節に進みます。 アカウントの設定の「API キー」の節。キーがまだないときは「API キーを作成」のボタンだけが表示される

2. 作成する

「API キーを作成」を選びます。どこで使うキーか分かる名前(例: ci-nightly)を入力します。名前は 100 文字以内で、ほかのキーと重ならないようにします。

3. 有効期限を選ぶ

7 日、30 日、90 日、1 年、日付の指定、無期限から選びます。既定は 30 日です。管理者が、これより短い上限を決めていることがあります。選んだら、「作成」を選びます。 「新しい API キー」の入力欄。名前、有効期限(7 日、30 日、90 日、1 年、日付を指定、無期限)、権限(読み取りのみ)が並ぶ

4. キーをコピーする

キーが表示されるのは、このときだけです。コピーして、パスワード管理ツールや CI のシークレットに保管します。
キーは、名前、有効期限、最終使用とともに一覧に並びます。値は二度と表示されません。
キーをなくしたときは、「再生成」で新しい値を発行します。古い値はすぐに使えなくなります。キーを変更する前に、サインアウトして、もう一度サインインするよう表示されたときは、そのとおりにしてから、やり直します。

キーを expl に渡す

expl server login --with-token でキーを保存するか、環境変数 EXPL_SERVER_TOKEN に設定します。環境変数が先に使われます。選ばれる順と切り替え方は、サインインにあります。--token は削除されました。指定すると、終了コード 2 で終わります。 GitHub Actions での使い方は、自動処理を参照してください。

ターミナルで作る・一覧する・取り消す

これらのコマンドは、ブラウザでサインイン(expl server login)したときだけ使えます。API キーでは、expl server token create は「Log in with “expl server login” to create tokens.」というエラーで失敗します。
--name は必須です。ターミナルから作るときの名前には、英数字と「.」「_」「-」を使え、1〜64 文字です。--expires <days> で、キーが使える日数を 1〜365 の範囲で指定できます。この方法で作ったものも API キーで、アカウント設定 > API キーに並びます。キーが表示されるのは 1 回だけなので、すぐに保管します。 実行結果
キーの一覧を表示します。キーの値は表示されません。キーがないときは「No tokens.」と表示されます。 実行結果
ci は、作るときに付けた名前です。 実行結果

キーを安全に扱う

  • キーをコマンドラインやスクリプトに書かないでください。シェルの履歴に残り、プロセスの一覧からも見えます。expl server login --with-token(キーを表示せずに聞きます)か、環境変数を使います。
  • CI では、キーをシークレットとして渡し、ログに出さないようにします。自動処理を参照してください。
  • キーには有効期限があります。期限の 7 日前と 1 日前に、メールが届きます。ジョブが止まらないよう、それまでに新しいキーを作ってください。
  • キーが作成・再生成・取り消しされたときも、メールが届きます。心当たりがないときは、キーを取り消して、パスワードを変更してください。

キーを取り消す

キーが漏れたときや、使わなくなったときは、取り消します。アカウント設定 > API キーで「取り消し」を選ぶか、ブラウザでサインインしたあとに expl server token revoke <name> を実行します。このコマンドは、確認なしで、--yes がなくても取り消しを送ります。キーはすぐに使えなくなります。 取り消した、期限切れの、または間違ったキーでの呼び出しは、終了コード 4 で終了し、「The API key is invalid or expired. Create a new one in Account Settings > API Keys. (UNAUTHORIZED)」と表示します。

管理者が決められること

オンプレミス環境と Hosted 環境では、管理者が管理画面で次のことを決められます。
  • API キーをオフにする。すべてのキーがすぐに使えなくなり、設定をオンに戻すと、また使えます。メッセージは「API keys are disabled by your administrator.」です。
  • キーの最長有効期間を決める。それより長い有効期間のキーは使えなくなります。
  • キーを使える IP アドレスを限定する。メッセージは「This IP address is not allowed for API keys.」です。
  • 全ユーザーのキーを確認・取り消す。持ち主にメールが届きます。

記録されるもの

API キーは、ハッシュで保存され、作成日時、有効期限、最終使用日時が記録されます。そのほかの記録は、MCP Server のデータと権限のページにまとめています。