签发访问令牌

POST/v2/auth/token

使用账号密码或客户端凭证换取 access_token 与 refresh_token。

这是唯一的免鉴权写接口。返回的 access_token 有效期 2 小时，refresh_token 有效期 30 天且一次性轮换：每次刷新都会签发新的 refresh_token，旧的在 5 秒宽限期后失效。

免鉴权 10 次 / 分钟 / IP api.demo.acme-cloud.dev

请求参数

共 1 项

X-Device-Id 可选请求头

string

设备指纹，用于风控与登录态审计

请求体

application/json

grant_type 必填

string · 默认 password

授权类型

可选值passwordclient_credentialsrefresh_token

username 必填

string

登录账号（邮箱或手机号）

password 必填

string

账号密码，服务端使用 Argon2id 校验

scope 可选

string

申请权限范围，空格分隔；留空则取角色默认权限集

mfa_code 可选

string

已开启两步验证的账号必须携带 6 位动态码

响应

3 种状态

200 OK —— 令牌签发成功

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzdmM2EyMSJ9.demo",
  "refresh_token": "rt_8c41d0ecb9a24f3d8a6b",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "users:read instances:write"
}

代码示例

cURL

curl -i -X POST 'https://api.demo.acme-cloud.dev/v2/auth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Device-Id: web-8f2c1a' \
  -d '{
  "grant_type": "password",
  "username": "ada@acme.com",
  "password": "••••••••",
  "scope": "users:read instances:write"
}'

注意事项

不要在浏览器前端硬编码账号密码，生产环境请使用 client_credentials 或 PKCE 流程。
登录失败计数按 账号 + 客户端 IP 双维度累计，5 次触发 15 分钟锁定。