跳到正文

快速开始

认证

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

密钥标识一个工作区和一名成员,并记录它能做什么。本页介绍如何发送密钥、它允许什么、它的限制,以及如何保护它。

发送密钥#

除了公开的 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中创建密钥。一个工作区最多有 25 个有效密钥。

Scope#

一个 scope 对应一族工具。每个工具要求各自的 scope,见工具目录。

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

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

有效期与撤销#

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

限制#

每个密钥的限制默认值超出时
每分钟请求数120429 rate_limited,并带有 Retry-After
每分钟智能体轮数10429 rate_limited,并带有 Retry-After
每日请求数20,000429 quota_exceeded

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

用量与历史#

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

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

保护密钥#

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

对 API 有疑问,或发现本页有误? 联系我们.