使用 PIN API 密钥与智能体令牌认证

如何使用 Bearer API 密钥或节点智能体 HMAC 令牌对咏唱引擎 PIN API 进行认证，包括引导密钥与公开路由。

PIN API 采用双认证模型。大多数接口需要使用用户创建的 Bearer API 密钥，而内部智能体回调接口使用单独的 HMAC 令牌方案。

Bearer API 密钥 在每次请求的 Authorization 头中携带你的密钥：

Authorization: Bearer <your-api-key>

你可以使用 PIN 服务器上的 ADMIN_API_KEY 环境变量引导创建第一个密钥，或通过 /v1/apikeys 接口创建用户作用域的密钥。API 密钥的作用域限定为创建它的用户。

公开路由 以下路由无需认证：

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

节点智能体 HMAC 令牌 /v1/agent/* 下的路由使用节点智能体 HMAC 令牌，这是一种为内部智能体回调设计的独立认证方案。这些令牌并非用户管理的 API 密钥。

示例请求

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

如果密钥缺失或无效，PIN 会返回 401 Unauthorized，并附带错误信封：

{
  "error": "unauthorized",
  "detail": "invalid or missing api key"
}