はじめに
認証
キーがワークスペースを識別する仕組み、許可される内容、保護の方法。
キーはワークスペースとメンバーを識別し、許可される操作の一覧を持ちます。このページでは、キーの送り方、許可される内容、制限、保護の方法を説明します。
キーの送信#
公開されている GET/api/v1 と GET/api/v1/openapi.json を除き、すべてのルートで Authorization ヘッダーにキーを入れます。
Authorization: Bearer piq_live_…Authorization を設定できないクライアントのために、x-api-key: piq_live_… ヘッダーも使えます。
キーは piq_live_ で始まり、その後に 38 文字が続きます。設定画面には、キーを見分けられるよう、プレフィックスの後の最初の 6 文字が表示されます。残りは二度と表示されません。
キーが表すもの#
キーは、作成したメンバーに代わって、そのメンバーのワークスペースで、そのメンバーのロールで動作します。ダッシュボードのルールはそのまま適用されます。キーが別のワークスペースを参照することはなく、作成者がワークスペースを離れるとキーは使えなくなります。
キーを作成できるのはオーナーと管理者だけです。作成は設定 → API と MCPで行います。1 つのワークスペースで有効にできるキーは最大 25 個です。
スコープ#
スコープは、ツールのまとまりを開きます。各ツールには必要なスコープがあり、カタログに記載しています。
| スコープ | 開く内容 |
|---|---|
read | コーパスとワークスペースの読み取り。ソース、アイテム、トピック、シグナル、エンティティ、ボード、テーブル、Upwork パイプライン。 |
explore | Web、SNS、レジストリ、アーカイブのライブ読み取り。ワークスペースのクレジットを使います。 |
write | ワークスペースへの書き込み。ボード、テーブル、追跡中のエンティティ、ウォッチ契約、プロファイル、Upwork の下書き。 |
act | モニタリングの操作。ソースの購読と解除、シグナルルールの設定、調査の開始、キャンペーンの追跡。 |
agents | Piqline、Requête、Facebook、LinkedIn、Upwork、オンボーディングの各エージェントによる回答。ワークスペースのクレジットを使います。 |
必要最小限を選んでください。コーパスの読み取りには read で足ります。エージェントに回答させるには agents を追加します。キーで実行したエージェントは、そのキー自身が呼び出せるツールだけを使います。
有効期限と失効#
キーは無期限にも、90 日または 1 年で失効するようにもできます。失効させるには、設定 → API と MCPを開き、失効 をクリックして キーを失効 をクリックします。そのキーを使う呼び出しは、1 分以内に 401 を返すようになります。
制限#
| キーごとの制限 | 既定値 | 超過したとき |
|---|---|---|
| 1 分あたりのリクエスト数 | 120 | 429 rate_limited(Retry-After 付き) |
| 1 分あたりのエージェントのターン数 | 10 | 429 rate_limited(Retry-After 付き) |
| 1 日あたりのリクエスト数 | 20,000 | 429 quota_exceeded |
すべてのレスポンスに、RateLimit-Limit(1 分あたりに許可されるバースト数)と RateLimit-Remaining(残り)が入ります。1 分あたりの制限はバーストを抑えるためのもので、サーバーインスタンスごとに適用されます。記載の値よりわずかに多く通る場合があります。GET/api/v1/workspace は、キーの制限と本日のリクエスト数を返します。
利用状況と履歴#
設定の API と MCP には、直近 30 日間の利用状況がツール別とエージェント別に表示されます。各リクエストの履歴には、時刻、操作、ステータス、所要時間、エラー、入力の抜粋、クライアント、送信元ネットワークが含まれます。履歴は 30 日間保持されます。
キーも、リクエスト本文の全体も保存しません。入力の抜粋は 300 文字で切り詰められ、シークレットに見えるフィールド(password、token、key)はマスクされ、送信元は先頭のネットワーク部分(IPv4 は /24、IPv6 は /48)だけを保持します。完全な IP アドレスは保存しません。
キーを保護する#
- シークレット管理ツールか環境変数に保存します。リポジトリ、Web ページ、モバイルアプリには置かないでください。
- 用途ごとに(スクリプト、エージェント、同僚ごとに)1 つずつキーを作成し、見分けやすい名前を付けます。他のキーに影響せずに 1 つだけ失効できます。
- テスト用のキーには有効期限を設定します。
- 漏えいしたキーはすぐに失効させます。Piqline が保持するのはキーのフィンガープリントだけです。キーを再表示することはできず、新しいキーを作成するしかありません。
- キーは作成者の権限を引き継ぎ、作成者がチームを離れると停止します。長く使う場合は、連携専用のアカウントで作成してください。