OAuth接入文档

欢迎使用 WEEX OAuth服务。本指南旨在帮助第三方平台（以下简称“平台方”）安全、高效地接入WEEX 用户授权系统。您的平台可以在获得用户授权后，获取用户特定的API 密钥，从而代替用户进行行情查询、现货及合约交易等操作。

流程概览

整个接入流程主要分为三个步骤：

平台注册：联系 WEEX 商务注册您的平台信息，获取唯一的clientId和secret并配置回调地址等信息。
用户授权：引导 WEEX 用户登录并授权，获取临时的授权码（code）。
换取密钥：在后端使用 code 换取 access_token，再通过 access_token 获取最终的 API Key、Secret Key、Passphrase，用于后续的 API 调用。

接入准备

向WEEX提供以下信息完成平台注册：

配置项	说明	示例
平台名称	您的平台名称，将在用户授权页显示，只支持英文名称	MyTrading
WEEX UID	平台方关联的 WEEX 用户ID，用于身份关联	123456
隐私条款	您的平台隐私条款地址	https://www.mytrading.com/en/privacy-policy
服务条款	您的平台隐私条款地址	https://www.mytrading.com/en/terms-of-use
平台Logo	将显示在用户授权页的Logo图片
联系人	技术或商务联系人
邮箱	联系人的邮箱地址	[email protected]
电话	联系人的电话号码
回调地址	关键配置用户授权后，WEEX OAuth 服务器将重定向至此地址，并携带授权码。支持配置多个回调地址，但请求时必须完全匹配其中之一	https://api.mytrading.com/oauth/callback https://sandbox.mytrading.com/oauth/callback
出口 IP	为了确保通信安全，您需要提供平台服务器访问 WEEX 接口时的公网出口 IP 地址。WEEX 运维团队将为您配置白名单，未授权的 IP 将无法调用接口。	47.100.1.1, 47.100.1.2

接入步骤

1.拼接授权页面

# OAuth 授权页面示例
https://www.weex.com/oauth?
clientId={clientId}&
responseType=code&
scope=create:apikey&
redirectUri={redirectUri}&
state={state}&
codeChallenge={codeChallenge}&
codeChallengeMethod={codeChallengeMethod}

请求参数：

参数	说明	备注
clientId	商户身份标识	商户初始化完成后获得
responseType	响应类型	固定值：code
scope	权限范围	传 `create:apikey`
state	状态参数	随机字符串，防 CSRF 攻击
redirectUri	回调地址	必须在管理后台配置
codeChallenge	PKCE 挑战值	PKCE 挑战值，RFC 7636 规定格式：43-128 位的 [A-Z, a-z, 0-9, -, ., _, ~]
codeChallengeMethod	PKCE 方法	PKCE 方法，当前仅支持 S256

注：由于服务端强制PKCE，所以客户端需要生产pkce参数。

第一步：生成 Code Verifier (代码验证码)

客户端生成一个高熵的随机字符串 code_verifier。

要求：由 [A-Z, a-z, 0-9, -, ., _, ~] 组成。
长度：建议使用 43 位或以上（最大 128 位）。

第二步：生成 Code Challenge (代码挑战值)

对 code_verifier 进行 SHA256 哈希，然后进行 Base64URL 编码（且不得包含末尾的 = 填充符）。 code_challenge = Base64URL(SHA256(code_verifier))

Java

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import java.security.SecureRandom;

public class PKCEUtils {
    public static void main(String[] args) throws Exception {
        // 1. 生成 code_verifier (随机字符串)
        SecureRandom sr = new SecureRandom();
        byte[] codeValue = new byte[32];
        sr.nextBytes(codeValue);
        String codeVerifier = Base64.getUrlEncoder().withoutPadding().encodeToString(codeValue);

        // 2. 生成 code_challenge (S256)
        byte[] bytes = codeVerifier.getBytes(StandardCharsets.US_ASCII);
        MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
        byte[] digest = messageDigest.digest(bytes);
        String codeChallenge = Base64.getUrlEncoder().withoutPadding().encodeToString(digest);

        System.out.println("code_verifier: " + codeVerifier);
        System.out.println("code_challenge: " + codeChallenge);
    }
}

2. 授权成功回调

用户完成授权后，页面将会301重定向至 redirectUri 回调地址

# 假設 redirect_uri = https://www.example.com/callback
# 回調後的 URL：
https://www.example.com/callback/?
code=sS38ddda0ddPC342342hhfuiu&
state=1234abc

3.获取 access_token

接口信息：

URL: https://gateway.weex.com/v1/oauth/token
方法: POST
注：使用refresh_token刷新access_token成功后，原先的access_token会失效，即同一个refresh_token只会存在一个生效的access_token
签名：参考签名规则

请求参数：

参数	类型	是否必须	参数描述
grantType	string	是	授权类型，可选值：authorization_code、refresh_token
code	string	否	返回的授权码，grantType=authorization_code 时需传
redirectUri	string	否	回调地址，必须与授权时一致，grantType=authorization_code 时需传
codeVerifier	string	否	PKCE 原始值，grantType=authorization_code 时需传
refresh_token	string	否	刷新令牌，grantType=refresh_token 时需传

请求示例：

curl -v -X POST {url} \
  -H 'Client-Id: weex123456' \
  -H 'Sign: *******' \
  -H 'Timestamp: 1735689600000' \
  -H 'Nonce: Nonce' \
  -d '{
  "grantType": "authorization_code",
  "code": "auth_code_xxx",
  "redirectUri": "https://api.wundertrading.com/oauth/callback",
  "codeVerifier": "code-verifier-demo"
  }'

返回参数：

参数	类型	参数描述
accessToken	String	访问令牌
refreshToken	String	刷新令牌
tokenType	String	令牌类型，固定为 Bearer
expiresIn	int	access token 剩余有效期，单位秒
refreshExpiresIn	int	refresh token 剩余有效期，单位秒
scope	String	授权范围

返回示例：

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1774621008941,
    "data": {
        "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI3NzU0MDkwNjQwIiwiYXVkIjoiY2FnZSIsInNjb3BlIjoiY3JlYXRlOmFwaWtleSIsImlzcyI6Imh0dHBzOi8vd2VleC5jb20iLCJleHAiOjE3NzQ2MjQ2MDgsImlhdCI6MTc3NDYyMTAwOCwianRpIjoiMzkifQ.mMVGvW0EeVO5TMxRiUDAyGmf64bcyEFXy0kz8xjv3wRp2pjsxpQUdT1Jn2V2SD0I6LhsCCRDp9Rhl6UuKnHYESBrqKWQONwf1nXTwIFB8Fmw_MqWFWVpi9nlaYBUIGiayuybllYZB1vN06fXRm5yq068UJFD_lSWMkrHJfUu5I7dD-JpwN9UNTsi5NY2a5vUc0WyBSPOnfnPBPr8x5PNB7uc9fr1Uew9QrmO2WnLuDCcDnZ2XGulzvmKC3b2ZXADDBKleuXAAgYzq-t-M4NBI2EjNP1wvpMGeTKyNTBKrXY4Wo0MQdipLGlKsr3cnpKdNqGWi9SzBSp-KctcGrpGew",
        "refreshToken": "o_3ubYfLM9zaqbwF_Xo9Jb13vyq-KPP6sVlGEAL3TjrBmbzao-xuT82VDVRFA-bCGuim2V-A_6vCbIiZsvdbjIefaGKaskNubXM9Wk3--7QwoSDqtpsUyD9KnJtoqToe",
        "tokenType": "Bearer",
        "expiresIn": 3600,
        "refreshExpiresIn": 36000,
        "scope": "create:apikey"
    }
}

4.获取Apikey

接口信息：

URL: https://gateway.weex.com/v1/oauth/resource/create-api
方法: POST
認證: 需要在請求頭中攜帶 Authorization 信息
格式：Bearer {access_token}
示例：Authorization: Bearer 12345

注：

同一个用户只能创建一个用户绑定三方的apikey，即只有用户不存在已绑定该三方的apikey时，接口才能调用成功。需重新绑定时，用户需要先删除原先已绑定的apikey。
调用创建api key成功后，需要妥善保存apikey、secret、passphrase，只有在第一次调用成功后才会返回以上3个参数
如果用户当前API状态不是正常，创建的APIKEY存在不能立马使用的情况。

请求示例：

curl {url} \
  -H "Authorization: Bearer {access_token}"

返回示例：

{
  "code": "00000",
  "data": {
    "apiKey": "ak_xxxxxxxxx",
    "secret": "sk_xxxxxxxxx",
    "passphrase": "pp_xxxxxxxxx"
  },
  "msg": "success",
  "requestTime": "1768529101682"
}

错误示例

{
  "code": "80000",
  "msg": "param error",
  "requestTime": "1768529101682"
}

响应码列表

响应码	响应信息	响应描述
00000	success	请求成功
40400	resource not found	接口路径不存在或资源不存在
80000	param error	请求参数错误
80002	client invalid	client 无效
80003	client auth failed	客户端签名验证失败
80004	PKCE code_verifier verification failed	客户端 PKCE 校验失败
80005	client mismatch	client 不匹配
80006	expired request	请求已过期
80007	replay request	重放请求
80008	uid duplicate	该 uid 已绑定 client
80009	client unauthorized	client 无权限
80010	user invalid	user 无效
80100	code invalid	授权码无效
80200	redirect uri invalid	redirect uri 无效
80201	redirect uri mismatch	redirect uri 不匹配
80300	access token invalid	access token 无效
80301	access token auth fail	access token 鉴权失败
80400	refresh token invalid	refresh token 无效
80500	grant type invalid	grant_type 无效
80600	scope invalid	scope 无效
80601	scope insufficient	scope 权限不足
80700	unsupported response type	不支持的 response type
80800	state invalid	state 无效
80900	code challenge invalid	PKCE code_challenge 无效
80901	code challenge method invalid	PKCE code_challenge_method 无效
81000	api key permission invalid	API Key 权限无效
81001	api key already bound	API Key 已绑定
81002	user api key num exceeds max limit	用户 API Key 数量超过最大限制

安全与规范

保护密钥:

client_secret、code_verifier 以及最终获取的 secret_key 和 passphrase 都必须存储在后端，严禁放在前端代码或移动应用中。

验证 State:

严格验证回调中的 state 参数，防止 CSRF 攻击，建议使用随机字符串。

使用 HTTPS:

所有 API 请求必须通过 HTTPS 发起。

流程概览​

接入准备​

接入步骤​

1.拼接授权页面​

2. 授权成功回调​

3.获取 access_token​

4.获取Apikey​

错误示例​

安全与规范​

保护密钥:​

验证 State:​

使用 HTTPS:​