# 认证

> 密钥如何标识工作区、它允许什么，以及如何保护它。

Source: https://piqline.com/zh/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)中创建密钥。一个工作区最多有 25 个有效密钥。

## Scope

一个 scope 对应一族工具。每个工具要求各自的 scope，见[工具目录](/zh/docs/api/tools#工具目录)。

| Scope | 开放的能力 |
| --- | --- |
| `read` | 读取语料库和工作区：来源、条目、主题、信号、实体、看板、表格、Upwork 管道。 |
| `explore` | 实时读取网络、社交网络、注册库和档案。会消耗工作区积分。 |
| `write` | 写入工作区：看板、表格、已关注的实体、监控合约、档案、Upwork 草稿。 |
| `act` | 对监控执行操作：订阅或取消订阅来源、设置信号规则、启动调查、关注活动。 |
| `agents` | 让 Piqline、Requête、Facebook、LinkedIn、Upwork 和 onboarding 智能体作答。会消耗工作区积分。 |

只选择最少够用的 scope。读取语料库只需 `read`；要让智能体回答，再加上 `agents`。使用你的密钥运行的智能体，只能使用该密钥自己可以调用的工具。

## 有效期与撤销

密钥可以永不过期，也可以在 90 天或一年后过期。要撤销密钥，请打开[设置 → API 和 MCP](/settings/api)，点击 **撤销**，再点击 **撤销密钥**。使用该密钥的调用会在一分钟内收到 `401`。

## 限制

| 每个密钥的限制 | 默认值 | 超出时 |
| --- | --- | --- |
| 每分钟请求数 | 120 | 429 `rate_limited`，并带有 `Retry-After` |
| 每分钟智能体轮数 | 10 | 429 `rate_limited`，并带有 `Retry-After` |
| 每日请求数 | 20,000 | 429 `quota_exceeded` |

每个响应都带有 `RateLimit-Limit`（每分钟允许的突发请求数）和 `RateLimit-Remaining`（剩余数量）。每分钟限制用于抑制突发流量：它按服务器实例计算，实际放行的请求可能略多于标明的数值。`GET /api/v1/workspace` 返回密钥的限制和今天已发出的请求数。

## 用量与历史

设置 → API 和 MCP 显示最近 30 天按工具和按智能体统计的用量，以及每个请求的历史：时间、操作、状态、耗时、错误、输入摘录、客户端和来源网络。历史保留 30 天。

历史中既没有密钥，也没有完整的请求体：输入摘录截断在 300 个字符，看起来像机密的字段（password、token、key）会被遮盖，来源网络只保留前缀（IPv4 为 /24，IPv6 为 /48），不保存完整 IP 地址。

## 保护密钥

- 把它保存在密钥管理器或环境变量中。不要放进代码仓库、网页或移动应用。
- 每种用途（一个脚本、一个智能体、一位同事）创建一个密钥，并起一个你能认出的名字：这样可以只撤销其中一个，不影响其他密钥。
- 给测试密钥设置有效期。
- 密钥一旦暴露，立即撤销。Piqline 只保存它的指纹：无法把密钥还给你，只能创建新密钥。
- 密钥沿用创建者的权限，创建者离开团队后密钥随之停用。长期使用的集成，请用专门为它准备的账号创建密钥。
