# 認証

> キーがワークスペースを識別する仕組み、許可される内容、保護の方法。

Source: https://piqline.com/ja/docs/api/authentication

キーはワークスペースとメンバーを識別し、許可される操作の一覧を持ちます。このページでは、キーの送り方、許可される内容、制限、保護の方法を説明します。

## キーの送信

公開されている `GET /api/v1` と `GET /api/v1/openapi.json` を除き、すべてのルートで `Authorization` ヘッダーにキーを入れます。

```http
Authorization: Bearer piq_live_…
```

`Authorization` を設定できないクライアントのために、`x-api-key: piq_live_…` ヘッダーも使えます。

キーは `piq_live_` で始まり、その後に 38 文字が続きます。設定画面には、キーを見分けられるよう、プレフィックスの後の最初の 6 文字が表示されます。残りは二度と表示されません。

## キーが表すもの

キーは、作成したメンバーに代わって、そのメンバーのワークスペースで、そのメンバーのロールで動作します。ダッシュボードのルールはそのまま適用されます。キーが別のワークスペースを参照することはなく、作成者がワークスペースを離れるとキーは使えなくなります。

キーを作成できるのはオーナーと管理者だけです。作成は[設定 → API と MCP](/settings/api)で行います。1 つのワークスペースで有効にできるキーは最大 25 個です。

## スコープ

スコープは、ツールのまとまりを開きます。各ツールには必要なスコープがあり、[カタログ](/ja/docs/api/tools#カタログ)に記載しています。

| スコープ | 開く内容 |
| --- | --- |
| `read` | コーパスとワークスペースの読み取り。ソース、アイテム、トピック、シグナル、エンティティ、ボード、テーブル、Upwork パイプライン。 |
| `explore` | Web、SNS、レジストリ、アーカイブのライブ読み取り。ワークスペースのクレジットを使います。 |
| `write` | ワークスペースへの書き込み。ボード、テーブル、追跡中のエンティティ、ウォッチ契約、プロファイル、Upwork の下書き。 |
| `act` | モニタリングの操作。ソースの購読と解除、シグナルルールの設定、調査の開始、キャンペーンの追跡。 |
| `agents` | Piqline、Requête、Facebook、LinkedIn、Upwork、オンボーディングの各エージェントによる回答。ワークスペースのクレジットを使います。 |

必要最小限を選んでください。コーパスの読み取りには `read` で足ります。エージェントに回答させるには `agents` を追加します。キーで実行したエージェントは、そのキー自身が呼び出せるツールだけを使います。

## 有効期限と失効

キーは無期限にも、90 日または 1 年で失効するようにもできます。失効させるには、[設定 → API と MCP](/settings/api)を開き、**失効** をクリックして **キーを失効** をクリックします。そのキーを使う呼び出しは、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 が保持するのはキーのフィンガープリントだけです。キーを再表示することはできず、新しいキーを作成するしかありません。
- キーは作成者の権限を引き継ぎ、作成者がチームを離れると停止します。長く使う場合は、連携専用のアカウントで作成してください。
