APIキー
Shanoneへのすべての外部リクエストは——MCPサーバー経由であれREST API経由であれ——次の形式のAPIキーで認証します。X-API-Key: sh_xxxxxxxxxxxxxxxxも利用できます。
キーを作成する
1
サインインする
app.shanone.aiにアクセスしてサインインします。
2
API Keysを開く
Settings → API Keysに移動します。
3
キーを作成する
Create API Keyをクリックし、わかりやすい名前を付けて有効期限を選択します。初期値は30日です。
4
キーをコピーする
作成をクリックし、表示された平文のキーをコピーします。再表示はできないため、画面を閉じる前に安全な場所に保存してください。
有効期限
APIキーの作成時に、利用できる期間を選択できます。
有効期間は、Shanoneがキーを作成した時刻からサーバーの時計で計算します。1日は24時間です。キーを使用しても期限は延長されません。作成完了画面とAPIキー一覧には、タイムゾーンを含む有効期限の日時が表示されます。
既存の無期限キーは、そのまま無期限で利用できます。30日の初期値は新規作成するキーに適用され、既存キーに期限が追加されることはありません。新しいキーを無期限にする場合は、作成時に無期限を明示的に選択してください。
期限が切れたとき
有効期限の時刻に達すると、そのキーではREST APIとMCPサーバーへの新しいリクエストを認証できなくなります。期限切れのキーは削除されず、APIキー一覧に期限切れとして残ります。
作成後の有効期限の延長や、期限切れ・無効化済みキーの再有効化はできません。新しいキーを作成し、古いキーを設定していたクライアント、環境変数、シークレットを更新してください。利用を中断させないために、期限が切れる前にキーのローテーションを行ってください。
期限切れや無効化は、新しく行われる認証に適用されます。すでに認証済みの処理やストリームを途中で取り消すものではありません。
キーのスコープを設定する
各キーは、デフォルトの設定に加えて、任意で制限を加えることができます。
利用可能な
permissionsの値:
permissionsを指定しなかったキーはフルアクセス権を持ちます。完全には信頼していないスクリプトやサービスに組み込むキーは、スコープを絞り込んでください。
直接MCPエンドポイントにはもう一つ必要なものがある
Shanoneのローカルstdioプロキシを経由せず、https://app.shanone.ai/mcp(Streamable HTTP)に直接接続する場合は、セカンドファクターとして**組織ID(organization ID)**も必要になります。これはX-Org-Idとして送信します(カスタムヘッダーを設定できないクライアントのフォールバックとして、URLの?org_id=も使えます)。
/api/v1/tools/...など)とローカルstdioプロキシは、この第二要素を必要としません。これらはAPIキー単体で認証します。
リクエストの例
- cURL
- Python
- JavaScript
レート制限
制限に恒常的に達してしまう場合は、Settings → API Keysからキーの上限を上げてください。
キーの管理
キーのローテーション
1
新しいキーを作成する
現在のキーの期限が切れる前に、Settings → API Keysから新しいキーを作成し、有効期限を選択します。
2
クライアント・スクリプトを更新する
古いキーが設定されていた箇所を、新しいキーに置き換えます。
3
古いキーを無効化する
新しいキーが正しく動作することを確認したうえで実施します。
無効化と削除の違い
有効なキーを無効化するには、Settings → API Keysで対象キーの**…メニューから無効化を選び、確認画面で確定します。無効化が完了すると、新しい認証は拒否されます。キーは無効化済み**として一覧に残るため、記録を保持できます。 削除を選ぶと、キーの記録を削除し、それ以降の認証も拒否します。どちらの操作も取り消せません。引き続きアクセスが必要なクライアントでは、新しいキーに切り替えてから古いキーを無効化・削除してください。漏洩が疑われるキーは、すぐに無効化してください。セキュリティのベストプラクティス
環境変数を使う
キーをコミット済みの設定ファイルやソースファイルにハードコードしないでください。
必要な範囲にスコープを絞る
permissionsとallowed_ipsを制限し、キーが必要な期間に合わせて有効期限を選んでください。マシン・エージェントごとに1つのキー
他に影響を与えずに個別に無効化できるようにするためです。
定期的にローテーションする
期限が切れる前に新しいキーへ切り替えてください。無期限キーも含め、漏洩したキーや不要になったキーは無効化してください。