生成 JWT 访问令牌
POST /api/auth/token
POST https://<api-host>/api/auth/token使用 X.509 客户端证书 + 凭证（clientId/clientSecret）进行身份验证并获取 JWT 令牌。令牌有效期由 expires_in 字段（单位：秒）给出：请根据该值在过期前续期，不要假定固定时长。
身份验证（mTLS）
此接口要求 mTLS：Gateways 签发的客户端证书在 TLS 握手中出示，而不是放在 HTTP 请求头中。请使用 HTTP 库自带的客户端证书机制（例如 curl --cert client.crt --key client.key）。
- 证书为 PEM 格式、RSA 2048，有效期 2 年，并与您的账户绑定。
- 仅此接口要求 mTLS。其他接口使用
Authorization: Bearer <token>，无需证书。
不要通过 HTTP 请求头发送证书：该方式不被接受。如果握手中没有证书，API 将返回 400 和 PUB_CERT_HEADER_MISSING。
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
clientId | string (UUID v4) | 是 | 在控制台（https://<dashboard-host>）的 设置 → 凭证 中生成的 Client ID |
clientSecret | string | 是 | 与 clientId 一同生成的 Client secret，在控制台中仅显示一次。不能为空 |
{
"clientId": "6967c0a0-3566-48d0-8c13-717038b52279",
"clientSecret": "YOUR_CLIENT_SECRET"
}cURL 示例
curl -X POST https://<api-host>/api/auth/token \
--cert ./client.crt \
--key ./client.key \
-H "Content-Type: application/json" \
-d '{
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET"
}'代码示例
const https = require('https');
const fs = require('fs');
const axios = require('axios');
const httpsAgent = new https.Agent({
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
});
const response = await axios.post(
'https://<api-host>/api/auth/token',
{
clientId: process.env.PIX_API_CLIENT_ID,
clientSecret: process.env.PIX_API_CLIENT_SECRET,
},
{ httpsAgent },
);
console.log('Token:', response.data.access_token);
console.log('Expires in:', response.data.expires_in, 'seconds');Gateways 以 PEM 格式（client.crt + client.key）提供证书。如果您的平台需要 .pfx/.p12 文件（Java 和部分 Windows/.NET 环境常见），请在本地转换：
openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12转换在您自己的机器上进行；Gateways 不提供 PFX 文件。
响应 (201)
| 字段 | 类型 | 描述 |
|---|---|---|
access_token | string | 用于 Authorization: Bearer <token> 请求头的 JWT 令牌 |
token_type | string | 固定为 Bearer |
expires_in | number | 令牌有效期（秒）。请根据该值在过期前续期 |
scope | string | 令牌作用域 |
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}错误
| 状态码 | 错误码 | 描述 |
|---|---|---|
| 400 | PUB_CERT_HEADER_MISSING | TLS 握手中未出示客户端证书 |
| 400 | PUB_CERT_MALFORMED_PEM | 证书的 PEM 格式无效 |
| 400 | PUB_REQUEST_BODY_INVALID | 请求体无效（例如 clientId 不是 UUID v4、clientSecret 为空、包含多余字段）。出错字段列在 details.violations 中 |
| 401 | PUB_INVALID_CREDENTIALS | clientId/clientSecret 无效 |
| 401 | PUB_CERT_NOT_VERIFIED | 连接中的证书无法验证 |
| 401 | PUB_CERT_NOT_REGISTERED | 证书未注册 |
| 401 | PUB_CERT_EXPIRED | 证书已过期 |
| 401 | PUB_CERT_NOT_YET_VALID | 证书尚未进入有效期 |
| 403 | PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT | 证书未绑定到该凭证所属账户 |
| 502 | PUB_AUTH_UPSTREAM_ERROR | 认证服务出现意外错误 |
| 503 | PUB_AUTH_UPSTREAM_UNAVAILABLE | 认证服务暂时不可用，请重试 |
{
"statusCode": 401,
"timestamp": "2026-04-17T15:24:28.809Z",
"path": "/api/auth/token",
"method": "POST",
"code": "PUB_INVALID_CREDENTIALS",
"message": "Invalid credentials provided",
"userMessage": "Invalid credentials.",
"errorId": "75d7999d6d7656b737e83435ced86ec6"
}有关完整的身份验证指南和令牌续期模式，请参阅 身份验证指南。