使用 PIN API Key 与 Agent Secret 鉴权

PIN API 的大部分请求用 Authorization: Bearer 鉴权。节点智能体控制面路由 /v1/agent/* 在这一层 Bearer 之上还要多一层共享 Secret。 Bearer 凭证：登录签发的 JWT 或长期 API key，放在 Authorization 头里：

Authorization: Bearer <jwt-or-api-key>

中间件接受 POST /v1/auth/login / POST /v1/auth/register 签发的 HS256 JWT，也接受通过 /v1/apikeys 创建的 API key。服务端首次启动时可能为管理员种子生成一把 API key，只在日志里打印一次，供 serve 配置为 ARIAPIN_API_KEY；没有 ADMIN_API_KEY 环境变量这种引导方式。密钥归创建它的用户所有。 公开路由（无需鉴权）：

GET /health
GET /version
POST /v1/auth/login
POST /v1/auth/register

节点智能体嵌套鉴权 /v1/agent/* 挂在已完成鉴权的 /v1 组里，所以每个智能体回调都要同时带上这两个头：

Authorization: Bearer <jwt-or-api-key>
X-Agent-Secret: <AGENT_REGISTER_SECRET>

X-Agent-Secret 必须等于服务端环境变量 AGENT_REGISTER_SECRET。这个变量为空时，智能体注册被禁用，相关路由返回 401。这是部署级共享 Secret，不是 HMAC 方案，也不是用户管理的 API key。 示例（用户路由）

curl -H "Authorization: Bearer $ARIA_PIN_KEY" \
  http://localhost:8001/v1/auth/me

示例（节点智能体路由）

curl -X POST http://localhost:8001/v1/agent/heartbeat \
  -H "Authorization: Bearer $ARIA_PIN_KEY" \
  -H "X-Agent-Secret: $AGENT_REGISTER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ag_01","status":"online"}'

凭证缺失或无效时返回 401：

{
  "code": 401,
  "data": null,
  "message": "unauthorized",
  "detail": "invalid token or api key"
}

PIN API

ROUTER API

AGENT API

MEMO API

使用 PIN API Key 与 Agent Secret 鉴权