请输入
菜单

获取系统访问令牌&标准认证

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 账户。

最近修改: 2026-10-29