认证 - VelaFi

VelaFi 分两步对 API 请求进行认证。首先，你的服务器使用 API key 和 API secret 对请求签名，并调用 GET /v2/token/generate 获取业务 token。然后，在之后每个需要认证的请求中，通过 X-BH-TOKEN 请求头发送该 token。API key 本身绝不能放在 X-BH-TOKEN 中。

请求头	值	发送场景
`X-BH-APIKEY`	你的 API key	仅 `GET /v2/token/generate`
`X-BH-TOKEN`	`GET /v2/token/generate` 返回的 token	其他所有需要认证的请求

切勿在任何请求头或参数中发送 API secret。它只保存在你的服务器上，仅用于计算 token 请求的 signature 查询参数。

开始之前

获取 token 之前，你需要满足以下全部三个条件：

已开通 API 访问。 VelaFi 必须为你的账户开通 API 访问权限。在开通之前，token 请求会以错误码 -5033 失败。
API key 和 API secret。 在 VelaFi 控制台的 API Management 页面创建。参见创建 API Key。
为 key 配置 IP 白名单。 未配置任何白名单 IP 地址的 key 无法获取 token（错误码 -1023）。请添加将要调用 API 的服务器的公网 IP 地址。

第 1 步 — 获取 Token

使用 API secret 对字符串 timestamp=<ms> 进行签名（HMAC-SHA256，小写十六进制），然后在 X-BH-APIKEY 请求头中携带 API key 调用 GET /v2/token/generate：

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(( $(date +%s) * 1000 ))
SIGNATURE=$(printf 'timestamp=%s' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

curl --request GET \
  --url "https://api-test.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  --header "X-BH-APIKEY: ${API_KEY}"

成功的响应包含 token 及其过期时间：

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "token": "09ef3523-6242-4a8d-80e2-24cfbdb35851",
    "expireTime": "1740568725231"
  }
}

第 2 步 — 发送 Token

在每个需要认证的请求中，将 token 放入 X-BH-TOKEN 请求头：

X-BH-TOKEN: your_token

示例 — 使用 curl 发送已认证的 GET 请求

curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: your_token"

完整的 token 请求参考请参见生成 Token。

Token 有效期

每个 token 都会过期。token 响应中的 expireTime 字段是以毫秒为单位的 Unix 时间戳形式的过期时间。请在该时间之前申请新的 token。使用已过期或未知 token 的请求会以错误码 -1022 失败。

认证错误

认证失败时返回 HTTP 状态码 400。响应体中的 code 字段为负数，用于标识具体问题：

{
  "code": -1022,
  "msg": "Signature for this request is not valid."
}

错误码	返回场景	含义
`-1002`	Token 请求	`X-BH-APIKEY` 请求头缺失或格式错误。
`-1002`	API 调用	`X-BH-TOKEN` 请求头缺失。
`-1004`	Token 请求	缺少 `signature` 查询参数，或在发送其他查询参数时缺少 `timestamp`。`msg` 会指明缺失的参数。
`-1103`	Token 请求	请求没有任何查询参数，或只有 `signature` 一个参数。
`-1022`	Token 请求	签名不匹配，或 API key 不存在。
`-1022`	API 调用	token 无效或已过期。请申请新的 token。
`-1023`	Token 请求或 API 调用	该 API key 未配置 IP 白名单。
`-2015`	Token 请求	API key 或你的账户已被禁用，或请求 IP 地址不在该 key 的白名单中。
`-2015`	API 调用	API key 已被禁用或删除，或你的账户已被禁用。
`-2019`	API 调用	请求 IP 地址不在该 key 的白名单中。
`-5033`	Token 请求	你的账户未开通 API 访问。请联系 VelaFi。

沙盒环境与生产环境密钥

沙盒环境
生产环境

在开发和 QA 阶段，将沙盒密钥与测试 base URL 搭配使用：

Base URL: https://api-test.velafi.com
Token:    GET https://api-test.velafi.com/v2/token/generate
Header:   X-BH-TOKEN: your_sandbox_token

沙盒环境中的交易不会转移真实资金。你可以放心地使用它来探索 API、测试边界情况，并在上线前端到端验证你的集成。

仅在集成完成并验证通过后，才将生产密钥与正式 base URL 搭配使用：

Base URL: https://api.velafi.com
Token:    GET https://api.velafi.com/v2/token/generate
Header:   X-BH-TOKEN: your_production_token

生产环境请求会发起真实的金融交易。请像保管加密私钥一样谨慎保管你的生产密钥。

切勿将沙盒环境凭证用于生产 URL，也不要将生产凭证用于沙盒环境 URL。请在配置中将两套凭证分开管理。

安全最佳实践

遵循以下实践来保护你的 API key，并在发生泄露时尽量降低风险。

切勿在客户端代码中暴露密钥

API key、API secret 和 token 只能在服务端代码中使用。不要将它们嵌入浏览器 JavaScript、移动应用二进制文件、公开代码仓库或任何终端用户可访问的环境中。请使用环境变量或密钥管理服务（例如 AWS Secrets Manager、HashiCorp Vault 或 GCP Secret Manager）在运行时注入密钥。

定期轮换密钥

制定密钥轮换策略（例如每 90 天一次），即使你没有理由怀疑密钥已泄露。在 API Management 页面创建新密钥，为其添加 IP 白名单，将系统切换到新密钥，然后删除旧密钥。

配置 IP 白名单

IP 白名单是必需的。未配置白名单的 key 无法获取 token（错误码 -1023）。来自不在白名单中的 IP 地址的 token 请求会以错误码 -2015 失败，来自此类地址的 API 调用会以错误码 -2019 失败。请将白名单限制为调用 API 的服务器。要进行设置，请在 VelaFi 控制台中打开 API Management，然后在对应的 key 上选择 Whitelist。每个 key 最多可添加 5 个 IPv4 或 IPv6 地址。请逐个输入地址；不支持 CIDR 网段。

监控异常使用

记录系统发出的每个 token 请求和 API 调用，并对非预期的调用发出告警。如果发现可疑活动，请在 API Management 页面删除该 key，创建新的 key，并联系 VelaFi 支持团队。

概览

账户

配置

商户

加密钱包

收款人

报价

订单

Webhooks

认证

开始之前

第 1 步 — 获取 Token

第 2 步 — 发送 Token

Token 有效期

认证错误

沙盒环境与生产环境密钥

安全最佳实践

​开始之前

​第 1 步 — 获取 Token

​第 2 步 — 发送 Token

​Token 有效期

​认证错误

​沙盒环境与生产环境密钥

​安全最佳实践

开始之前

第 1 步 — 获取 Token

第 2 步 — 发送 Token

Token 有效期

认证错误

沙盒环境与生产环境密钥

安全最佳实践