获取或刷新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": "your_access_token",
  "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": "your_access_token",
  "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": "your_access_token",
  "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

Responses

200

A successful response.

Response Headers

500

An unexpected error response.

Response Headers