鉴权认证

本指南介绍如何使用 JSON Web Tokens (JWT) 对您的 API 请求进行认证。

概览

BigONE API 使用 JWT Token 进行身份验证。您需要：

1. 使用您的 API Key 和 API Secret 创建一个 JWT Token
2. 将 Token 包含在请求的 Authorization 头中

curl "https://api.big.one/api/v3/viewer/accounts" \
     -H 'Authorization: Bearer <YOUR_TOKEN>'

JWT Token 结构

BigONE API 使用 JSON Web Tokens (JWT) 和 HS256 算法。

注意

签名 JWT 时，不要 对您的 API Secret 进行 Base64 编码；请按原样使用 API Secret。Base64 编码会导致 Token 无效。

JWT Header

Claim	类型	值
alg	string	"HS256"
typ	string	"JWT"

JWT Payload

Claim	类型	必填	描述
type	string	是	必须为 OpenAPIV2
sub	string	是	您的 API Key
nonce	string	是	纳秒级时间戳 (例如：1527665262168391000)
recv_window	string	否	允许的时间戳偏差（秒）。默认：30

关于 Nonce

nonce 用于防止重放攻击。nonce 与服务器当前时间的差值必须小于 recv_window 秒。

示例

Token 组成部分

让我们创建一个 Token：

• API Key: 765fc50d-39e0-11f0-9669-5a69d7ba6f46
• API Secret: testsecret

Header:

{
  "typ": "JWT",
  "alg": "HS256"
}

Payload:

{
  "type": "OpenAPIV2",
  "sub": "765fc50d-39e0-11f0-9669-5a69d7ba6f46",
  "nonce": "1527665262168391000"
}

签名后的 Token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoiT3BlbkFQSVYyIiwic3ViIjoiY2VlODhhYjBiYzY5NDM1Nzg0YjdkYjA1NDVlODU2NDciLCJub25jZSI6MTUyNzY2NTI2MjE2ODM5MTAwMH0.cJ_uPmDeIxEPbKb_Xi0YuCflt_kgok5lryPwDG-jrsM

您可以在 jwt.io 验证您的 Token。

Python

import jwt
import time

# 您的 BigONE API 凭证
API_KEY = 'your_api_key_here'
API_SECRET = 'your_api_secret_here'

# 生成 nonce: 当前纳秒级时间戳
nonce = int(time.time() * 1e9)

# 创建 JWT payload
payload = {
    "type": "OpenAPIV2",
    "sub": API_KEY,
    "nonce": str(nonce),
}

# 签名 Token
token = jwt.encode(payload, API_SECRET, algorithm="HS256")

print(f"Authorization: Bearer {token}")

Go

package main

import (
    "fmt"
    "time"
    "github.com/golang-jwt/jwt/v4"
)

func main() {
    apiKey := "your_api_key_here"
    apiSecret := "your_api_secret_here"
    
    // 生成纳秒级 nonce
    nonce := fmt.Sprintf("%d", time.Now().UnixNano())
    
    // 创建 claims
    claims := jwt.MapClaims{
        "type":  "OpenAPIV2",
        "sub":   apiKey,
        "nonce": nonce,
    }
    
    // 创建并签名 token
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    signedToken, err := token.SignedString([]byte(apiSecret))
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Authorization: Bearer %s\n", signedToken)
}

JavaScript

const jwt = require('jsonwebtoken');

const API_KEY = 'your_api_key_here';
const API_SECRET = 'your_api_secret_here';

// 生成纳秒级 nonce
const nonce = (BigInt(Date.now()) * BigInt(1000000)).toString();

// 创建 payload
const payload = {
    type: 'OpenAPIV2',
    sub: API_KEY,
    nonce: nonce,
};

// 签名 token
const token = jwt.sign(payload, API_SECRET, { algorithm: 'HS256' });

console.log(`Authorization: Bearer ${token}`);

发起认证请求

在请求头中包含 Token：

curl -X GET "https://api.big.one/api/v3/viewer/accounts" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

认证错误

HTTP 状态	代码	信息	描述
401	40004	Unauthorized	缺少 Authorization 头或无效
401	40106	Invalid Token	JWT 格式错误、签名无效或已过期
400	40107	Unexpected request header	Authorization 头格式不正确
403	10403	Permission denied	API Key 权限不足或 IP 不在白名单
404	10013	Resource not found	API Key 不存在或已被撤销

故障排除

常见问题与解决方案

1. 40004 Unauthorized: 确保您包含了 Authorization: Bearer <token> 请求头
2. 40106 Invalid Token:
   • 检查 JWT 是否使用原样 API Secret 签名（不要 Base64 编码 Secret）
   • 验证 nonce 是否在 recv_window 范围内（默认 30 秒）
3. 40107 Unexpected request header: 格式必须严格为 Bearer <token>（中间一个空格）
4. 10403 Permission denied:
   • 在 BigONE 设置 检查 API Key 权限
   • 验证您的 IP 是否在白名单中
5. 10013 Resource not found: API Key 可能已被删除

下一步

• 通用信息 — 频率限制和响应格式
• 错误代码 — 错误代码完整列表