获取或刷新token

POST /auth/v1/token

接口说明

获取或刷新token接口，支持多种OAuth 2.0标准授权模式，用于获取access_token和refresh_token。

授权模式说明

1. Refresh Token 刷新模式

入参要求：

grant_type: 授权类型（必填，固定值为"refresh_token"）
refresh_token: 刷新令牌（必填，用于获取新的access_token）
client_id: 应用对应的客户端id（可选，默认为环境id）
x-device-id: 设备id（可选，请求头中传入）

前置条件：

必须持有有效的refresh_token
refresh_token未过期且未被撤销

出参：

token_type: token类型，固定为"Bearer"
access_token: 访问令牌，用于访问受保护的资源
refresh_token: 新的刷新令牌，原refresh_token随即失效
expires_in: access_token过期时间（秒）
sub: 用户唯一标识

Refresh Token刷新请求示例

{
  "client_id": "demo-app-2f8a9c3e1b4d",
  "grant_type": "refresh_token",
  "refresh_token": "m.yPxK8mLnVrQwEoDzFcHbNtGsYvXpRjWq-3eSd2fA1gU5iI9kO0lP7uJ4mT6nB8yC"
}

Refresh Token刷新响应示例

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "refresh_token": "m.aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ5aB6cD7eF8gH9iJ0kL1mN2oP3qR4sT5uV6wX7yZ8",
  "expires_in": 7200,
  "sub": "9876543210123456789"
}

2. 密码模式认证

入参要求：

grant_type: 授权类型（必填，固定值为"password"）
username: 用户名（必填）
password: 密码（必填）
client_id: 应用对应的客户端id（可选，默认为环境id）
x-device-id: 设备id（可选，请求头中传入）

前置条件：

用户已注册并设置密码
用户名密码登录方式已开启

出参：

token_type: token类型，固定为"Bearer"
access_token: 访问令牌
refresh_token: 刷新令牌
expires_in: access_token过期时间（秒）
sub: 用户唯一标识

密码模式请求示例

{
  "client_id": "demo-app-2f8a9c3e1b4d",
  "grant_type": "password",
  "username": "zhangsan",
  "password": "DemoPass123!@#"
}

密码模式响应示例

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "refresh_token": "m.aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ5aB6cD7eF8gH9iJ0kL1mN2oP3qR4sT5uV6wX7yZ8",
  "expires_in": 7200,
  "sub": "9876543210123456789"
}

3. 客户端凭证模式

入参要求：

grant_type: 授权类型（必填，固定值为"client_credentials"）
client_id: 应用对应的客户端id（可选，默认为环境id）
Authorization: 认证信息（必填，请求头中传入，格式为"Basic ${base64(SecretId:SecretKey)}"）

前置条件：

必须持有有效的SecretId和SecretKey
调用方需具备服务端可信环境
SecretKey需存储于安全介质

出参：

token_type: token类型，固定为"Bearer"
access_token: 访问令牌，具有超级管理员权限
expires_in: access_token过期时间（秒）
注意：不返回refresh_token

客户端凭证模式请求示例

POST /auth/v1/token
Authorization: Basic bG93Y29kZS01ZzlhYzIwdTJhMjdkYTQ2OnNlY3JldF9rZXlfZXhhbXBsZQ==
Content-Type: application/json

{
  "client_id": "demo-app-2f8a9c3e1b4d",
  "grant_type": "client_credentials"
}

客户端凭证模式响应示例

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "expires_in": 7200
}

字段说明

请求参数

字段名	类型	必填	说明
grant_type	string	是	授权类型，可选值：refresh_token、password、client_credentials
refresh_token	string	否	刷新令牌，grant_type为refresh_token时必填
username	string	否	用户名，grant_type为password时必填
password	string	否	密码，grant_type为password时必填
client_id	string	否	客户端id，默认为环境id
x-device-id	string	否	设备id，请求头中传入
Authorization	string	否	认证信息，grant_type为client_credentials时必填，请求头中传入

响应参数

字段名	类型	说明
token_type	string	token类型，固定为"Bearer"
access_token	string	访问令牌，用于访问受保护的资源
refresh_token	string	刷新令牌，用于获取新的access_token（client_credentials模式不返回）
expires_in	integer	access_token过期时间（秒）
sub	string	用户唯一标识（client_credentials模式为service_account）

关键特性

Refresh Token刷新机制

符合RFC 6749 Section 6标准
原refresh_token使用后立即失效
返回新的access_token和refresh_token
支持无感刷新，提升用户体验

密码模式

符合RFC 6749 Section 4.3标准
适用于可信客户端
直接使用用户名密码获取token
返回access_token和refresh_token

客户端凭证模式

符合RFC 6749 Section 4.4标准
适用于服务端调用
自动授予超级管理员权限
不返回refresh_token
需要SecretId和SecretKey认证

安全规范

Refresh Token安全

refresh_token应安全存储在客户端
使用后立即失效，防止重放攻击
建议定期轮换refresh_token
检测到异常时应立即撤销

密码模式安全

仅在可信客户端中使用
密码应加密传输（HTTPS）
建议实现登录失败次数限制
支持验证码防护机制

客户端凭证模式安全

SecretKey必须存储于安全介质
仅在服务端可信环境中使用
定期轮换SecretKey
记录所有调用审计日志
限制调用频率和IP白名单

使用场景

Refresh Token刷新

access_token即将过期时自动刷新
实现无感登录体验
长期保持登录状态

密码模式

用户首次登录
可信的第一方应用
内部管理系统

客户端凭证模式

服务端API调用
后台管理操作
系统集成场景
需要管理员权限的操作

错误响应示例

{
  "error": "invalid_grant",
  "error_code": 4001,
  "error_description": "refresh_token无效或已过期"
}

Request

Query Parameters

client_id string

应用对应的客户端id，默认为环境id，可以不传

Header Parameters

x-device-id string

设备id，当前登录设备的id。客户端应随机生成，并缓存到客户端。此参数与登录账号数有关

application/json

Body

grant_type 获取token的授权方式 (string)nullable

code grant_type 为 authorization_code 时使用 (string)

refresh_token refresh_token 刷新token时, 使用 (string)

username grant_type 为 password时使用 (string)

password grant_type 为 password时使用 (string)

scope scope，可选 (string)

nonce 随机字符串, 可选 (string)

code_verifier PKCE: code_verifier (string)

device_code Device Code Flow https://tools.ietf.org/html/rfc8628 (string)

Responses

A successful response.

Response Headers

application/json

Schema
Example (from schema)

Schema

token_type 访问令牌类型 (string)

统一返回 Bearer

access_token 用户的访问令牌 (string)

用于访问云开发HTTP API的令牌，长度4096位以内

refresh_token 用户的刷新令牌 (string)

access_token过期可通过refresh_token刷新获取新的access_token，过期时间默认为31天。长度128位以内

expires_in int32

access_token的过期时间，单位为秒

scope 授权范围 (string)

sub 用户的唯一id (string)

groups string[]

{
  "token_type": "string",
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 0,
  "scope": "string",
  "sub": "string",
  "groups": [
    "string"
  ]
}

An unexpected error response.

Response Headers

application/json

Schema
Example (from schema)

Schema

error 错误信息 (string)

error_code int32

error_description 错误描述 (string)

{
  "error": "string",
  "error_code": 0,
  "error_description": "string"
}

获取或刷新token

/auth/v1/token

接口说明​

授权模式说明​

1. Refresh Token 刷新模式​

入参要求：​

前置条件：​

出参：​

Refresh Token刷新请求示例​

Refresh Token刷新响应示例​

2. 密码模式认证​

入参要求：​

前置条件：​

出参：​

密码模式请求示例​

密码模式响应示例​

3. 客户端凭证模式​

入参要求：​

前置条件：​

出参：​

客户端凭证模式请求示例​

客户端凭证模式响应示例​

字段说明​

请求参数​

响应参数​

关键特性​

Refresh Token刷新机制​

密码模式​

客户端凭证模式​

安全规范​

Refresh Token安全​

密码模式安全​

客户端凭证模式安全​

使用场景​

Refresh Token刷新​

密码模式​

客户端凭证模式​

错误响应示例​

Request​

Query Parameters

Header Parameters

Body

Responses​

接口说明

授权模式说明

1. Refresh Token 刷新模式

入参要求：

前置条件：

出参：

Refresh Token刷新请求示例

Refresh Token刷新响应示例

2. 密码模式认证

入参要求：

前置条件：

出参：

密码模式请求示例

密码模式响应示例

3. 客户端凭证模式

入参要求：

前置条件：

出参：

客户端凭证模式请求示例

客户端凭证模式响应示例

字段说明

请求参数

响应参数

关键特性

Refresh Token刷新机制

密码模式

客户端凭证模式

安全规范

Refresh Token安全

密码模式安全

客户端凭证模式安全

使用场景

Refresh Token刷新

密码模式

客户端凭证模式

错误响应示例

Request

Responses