跳到主要内容

认证指南

本指南逐步说明如何获取访问令牌以使用 CorpX PIX API。

概述​

CorpX API 使用 OAuth 2.0 的 Client Credentials 流程进行认证。您需要使用您的凭据（client_id 和 client_secret）来获取有效的访问令牌。

前提条件​

在开始之前，请确保您已具备以下信息：

  • Client ID - 您的唯一客户端标识符
  • Client Secret - 用于认证的密钥
  • X-Tenant-Id - 您的租户标识符（例如：tenant-suaempresa）
信息

如果您还没有凭据，请联系我们的支持团队。

环境​

环境认证 URLAPI URL备注
Sandbox（开发）——暂时停用。
生产环境https://auth.corpxapi.com/oauth2/tokenhttps://api.corpxapi.com

第一步：请求访问令牌​

请求​

curl -X POST "https://auth.corpxapi.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

参数​

参数类型必填描述
grant_typestring是固定为 client_credentials
client_idstring是您的客户端标识符
client_secretstring是您的密钥

成功响应 (200 OK)​

{
  "access_token": "eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
字段描述
access_token用于 API 调用认证的 JWT 令牌
expires_in有效期（秒），通常为 3600 = 1 小时
token_type令牌类型（固定为 Bearer）

错误响应 (401 Unauthorized)​

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

第二步：在请求中使用令牌​

获取令牌后，在所有 API 请求的 Authorization 头中携带该令牌。

示例：查询余额​

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0..." \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json"

必需的请求头​

请求头描述
Authorization格式为 Bearer {access_token} 的访问令牌
X-Tenant-Id您的租户标识符
Content-Type带有请求体的请求使用 application/json

第三步：续期令牌​

令牌会在 expires_in 指定的时间后过期。我们建议：

  1. 缓存令牌并记录其过期时间
  2. 在过期前续期 - 提前几分钟请求新令牌
  3. 处理 401 错误 - 如果收到 401 Unauthorized，重新获取令牌

自动续期示例 (Bash)​

#!/bin/bash

# Variables
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH_URL="https://auth.corpxapi.com/oauth2/token"

# Function to get token
get_token() {
  response=$(curl -s -X POST "$AUTH_URL" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "client_id=$CLIENT_ID" \
    -d "client_secret=$CLIENT_SECRET")
  
  echo "$response" | jq -r '.access_token'
}

# Get token
TOKEN=$(get_token)

# Use the token
curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: tenant-suaempresa"

不同语言的完整示例​

Python​

import requests

# Credentials
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"
TENANT_ID = "tenant-suaempresa"

# Get token
auth_response = requests.post(
    "https://auth.corpxapi.com/oauth2/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    }
)

token = auth_response.json()["access_token"]

# Use the token
headers = {
    "Authorization": f"Bearer {token}",
    "X-Tenant-Id": TENANT_ID,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.corpxapi.com/v1/accounts/{accountId}/balance",
    headers=headers
)

print(response.json())

Node.js​

const axios = require('axios');

const CLIENT_ID = 'your_client_id';
const CLIENT_SECRET = 'your_client_secret';
const TENANT_ID = 'tenant-suaempresa';

async function getToken() {
  const response = await axios.post(
    'https://auth.corpxapi.com/oauth2/token',
    new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET
    }),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
  );
  return response.data.access_token;
}

async function getBalance(accountId) {
  const token = await getToken();
  
  const response = await axios.get(
    `https://api.corpxapi.com/v1/accounts/${accountId}/balance`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Tenant-Id': TENANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

常见错误​

错误原因解决方案
invalid_clientClient ID 或 Secret 不正确检查您的凭据
invalid_grant无效的 grant type使用 client_credentials
401 Unauthorized令牌已过期或无效重新获取令牌
403 Forbidden令牌有效但无权限检查 X-Tenant-Id

最佳实践​

  1. 切勿将 client_secret 暴露在客户端代码（前端）中
  2. 使用环境变量存储凭据
  3. 实施令牌缓存以避免不必要的请求
  4. 监控过期时间并主动续期令牌
  5. 使用 HTTPS 进行所有通信

后续步骤​

现在您已了解如何进行认证，请探索其他指南：