AiLink 开放 API 采用系统访问令牌(PAT)认证。
认证方式
每次请求需要提供以下 Header:
| Header | 是否必填 | 说明 |
|---|---|---|
Authorization |
是 | Bearer <系统访问令牌>,令牌在控制台生成 |
请求示例:
curl -sS "https://ailink.nativex.com/api/user/self" \
-H "Authorization: Bearer <你的系统访问令牌>"
缺少该 Header 或令牌无效均返回 401。
获取凭证
系统访问令牌
系统访问令牌是调用管理类接口(本文档描述的接口)的身份凭证。
获取步骤:
登录 AiLink 控制台 → 「安全与访问」 → 「访问令牌」 → 点击创建并复制。
它是一段随机字符串,格式示意:
abcd1234efgh5678ijkl9012mnop3456
安全建议:
•妥善保管,视同密码。
•不要硬编码到前端或公开仓库;建议通过环境变量或密钥管理系统注入到你的服务端。
•泄漏后立即在同一页面重新生成,新令牌会自动吊销旧令牌。
•一个账户同时只有一个有效的访问令牌。
如需查看当前账号的用户 ID(例如用于排障或与支持团队沟通),可用系统访问令牌调用
GET /api/user/self,响应体 data.id 即为用户 ID。与「API Key」(sk-xxx)的区分
AiLink 涉及两种「令牌」,用途不同,不要混淆:
| 名称 | 用途 | 请求头写法 |
|---|---|---|
| 系统访问令牌 | 调用本文档所有管理类接口(创建/查询令牌、查看日志、管理账号) | Authorization: Bearer <令牌值> |
| API Key(令牌) | 调用大模型接口(/v1/chat/completions 等业务接口) |
Authorization: Bearer sk-xxx |
本文档「令牌管理」章节说的是创建 / 查询 / 管理 API Key,本身是通过「系统访问令牌」来完成的。可以理解为:
系统访问令牌 → 用来管理 → API Key → 用来调 → 大模型
两者都使用 Authorization: Bearer <值> 的写法,区别在于令牌值本身对应的身份和可调用的接口范围不同。
验证认证是否成功
拿到令牌后,用下面这条命令验证:
curl -sS "https://ailink.nativex.com/api/user/self" \
-H "Authorization: Bearer <你的系统访问令牌>"
成功响应示例(节选常用字段,完整字段见下方说明):
data 实际返回字段远多于下面列出的部分,还包含第三方绑定信息(github_id/discord_id/oidc_id/wechat_id/telegram_id/linux_do_id)、display_name、setting等字段,主要服务于控制台前端展示。普通接入场景通常只需关注 id、username、quota、used_quota、group、status 几项。{
"success": true,
"message": "",
"data": {
"id": 12345,
"username": "example_user",
"role": 1,
"status": 1,
"email": "user@example.com",
"group": "default",
"quota": 5000000,
"used_quota": 10000000,
"request_count": 128,
"permissions": { }
}
}
看到 success: true 即代表认证链路已打通,可以调用所有其他接口。
常见错误与排查
以下错误都会返回 HTTP 401:
| 场景 | 原因 | 处理 |
|---|---|---|
未提供 Authorization |
请求头缺失 | 补上 Header |
| 令牌无效或已被新令牌顶替 | 令牌为空、错误或已在控制台重新生成过 | 在控制台重新生成访问令牌,使用最新值 |
| 账号被封禁 | 账号状态异常 | 联系支持 |
其他相关 HTTP 状态:
| 状态码 | 场景 | 处理 |
|---|---|---|
| 403 | 权限层面拦截 | 检查是否访问了权限不足的接口(例如管理员接口) |
| 429 | 触发限流 | 指数退避后重试 |
FAQ
Q:能不能用 API Key(sk-xxx)调本文档的管理接口?
A:不能。API Key 只能调用大模型接口(/v1/*、/chat/* 等)。管理类接口只接受「系统访问令牌」。
Q:访问令牌会过期吗?
A:不会自动过期,直到你手动在控制台重新生成(旧令牌立即失效)。
Q:一个账户能生成多少个访问令牌?
A:同时只有 1 个有效令牌。每次重新生成会覆盖旧的。如需多环境隔离(生产 / 测试),建议为不同环境使用不同的 AiLink 账户。