OAuth 2.0 认证流程文档 #

1. 概述 #

基于 OAuth 2.0 授权码模式（Authorization Code Flow） 的认证授权流程。授权方可以通过此流程获取 accessToken，用于访问受保护的 API 资源。

角色说明:

• 客户端: 指在AxT创建APP的用户（也称被授权方）
• 用户: 指操作人
• 服务端: 指AxT验证授权方

2. 认证流程 #

+-------------------+
|       客户端       |
+-------------------+
        |
        | 1. 将用户跳转至请求OAuth授权
        |   GET https://dash.axtn.net/oauth/authorize
        |   ?clientId={clientId}
        |   &redirect_uri={uri}
        |   &state={state}
        |
        | 2. 用户登录验证
        v
+----------------------+
|      用户登录成功      |
+----------------------+
        |
        | 3. 生成code并重定向
        |   {redirect_uri}?code={code}&state={state}
        v
+-------------------+
|       客户端       |
+-------------------+
        |
        | 4. 校验state
        v
(若state验证失败则终止)
        |
        | 5. 使用code换取accessToken
        |   POST https://api.axtn.net/v1/oauth/access
        |   Body: {client_id, client_secret, code, redirect_uri}
        v
+-------------------+
|       服务端       |
+-------------------+
        |
        | 6. 颁发accessToken
        |   { "accessToken": "xyz123", "expiresIn": 3600 }
        v
+-------------------+
|       客户端       |
+-------------------+
        |
        | 7. 使用accessToken访问资源
        |   GET https://api.axtn.net/v1/o/me
        |   Header: Authorization: Bearer xyz123
        v
+-------------------+
|       服务端       |
+-------------------+
        |
        | 8. 返回用户授权的资源数据
        v
+-------------------+
|       客户端       |
+-------------------+

3. 详细请求流程 #

3.1 客户端将用户跳转至授权登录页面 #

请求方式: GET

请求URL:

https://dash.axtn.net/oauth/authorize?clientId={clientId}&redirect_uri={redirect_uri}&state={state}

参数说明:

用户完成登录并授权后，跳转回客户端并携带code #

跳转URL格式（GET）:

{redirect_uri}?code={code}&state={state}

携带参数说明:

3.2 客户端使用code换取accessToken #

请求方式: POST

请求URL:

https://api.axtn.net/api/v1/oauth/access

请求头:

Content-Type: application/json

请求Body:

{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "code": "abc123",
    "redirect_uri": "https://your-app.com/callback"
}

返回示例:

{
    "accessToken": "xyz123",
    "tokenType": "Bearer",
    "expiresIn": 28800
}

3.3 使用accessToken请求API资源 #

请求方式: GET

请求URL:

https://api.axtn.net/api/v1/o/me

请求头:

Authorization: Bearer xyz123

返回示例:

{
  "code": 200,
  "data": {
    "user": {
      "openId": "axt_15fd483903e9198109206c92866c9f33",
      "username": "Darf",
      "country": "CN",
      "active": true,
      "avatarUrl": "https://q2.qlogo.cn/headimg_dl?dst_uin=1680839&spec=640",
      "registrationTime": "2025-07-17T16:18:19.179092Z",
      "twoFactorAuth": false
    },
    "role": {
      "level": 1,
      "exp": 399,
      "prefix": "AT",
      "role": "USER"
    }
  },
  "message": "Success"
}