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

# 认证

> NexaLayer 推荐 AI Agent 直接使用 X-API-Key 认证。

# 认证

NexaLayer 支持 API Key 认证。AI Agent、脚本和自动化任务推荐每次请求直接携带 `X-API-Key`。

```bash theme={null}
curl "https://api.nexalayer.net/v1/account/info" \
  -H "X-API-Key: ak_your_key"
```

## 邮箱领取 API Key

```bash theme={null}
curl -X POST "https://api.nexalayer.net/v1/account/request-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "referral_code": "optional"
  }'
```

响应不会直接返回 API Key。系统会将 API Key 发送到邮箱：

```json theme={null}
{
  "success": true,
  "data": {
    "status": "email_sent",
    "claim_status": "granted",
    "trial_balance": 1,
    "backend_ready": true,
    "message": "If the email address is valid, the API key has been sent."
  }
}
```

同一个邮箱只能领取一次试用额度；再次请求只会重发已有 API Key。

## backend\_ready

`backend_ready` 是资源可用性的真实门槛：

* `true`：账号已经完成后端同步，可以继续查询产品、余额并创建 Session
* `false`：不要继续创建 Session，应该提示用户或重试账号同步

## 幂等请求

创建 Session、轮换、续费、充值等写操作建议携带 `Idempotency-Key`：

```text theme={null}
Idempotency-Key: create-session-20260710-001
```

Agent 可以安全重试同一个动作，避免网络抖动造成重复扣费或重复创建。