> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

```text theme={null}
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 密钥。

**示例请求**

```bash theme={null}
curl -H "Authorization: Bearer $ARIA_PIN_KEY" \
  http://localhost:8001/v1/auth/me
```

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

```json theme={null}
{
  "error": "unauthorized",
  "detail": "invalid or missing api key"
}
```