从 v1 迁移到 v2

API v1 已弃用。 目前仍可用，但将在未来版本中移除。请迁移到 v2，以使用完整端点集合、改进的身份验证、个人资料管理与发票操作。

变更内容

API v2 引入版本化 URL 结构、新端点组，并在现有 API 密钥方式之外提供可选的 Bearer 令牌身份验证流程。

方面	v1	v2
基础路径	`/customer/v1/`	`/customer/v2/`
认证 — API 密钥	标头 `X-ORBIT-KEY: <key>`	相同 — 无变化
认证 — Bearer 令牌	不支持	`Authorization: Bearer <token>`
许可证端点	`/customer/v1/licenses/...`	`/customer/v2/licenses/...`
IP 白名单	扁平端点	嵌套在 `/licenses/{id}/ips` 下
API 密钥管理	不可用	`/customer/v2/api-keys/...`
个人资料	不可用	`/customer/v2/profile/...`
发票	不可用	`/customer/v2/invoices/...`

身份验证 — 无需变更

若使用 X-ORBIT-KEY 标头认证，认证方面无需变更。同一密钥可用于 v2。

# Works with both v1 and v2
curl -H "X-ORBIT-KEY: YOUR_API_KEY" https://api.orbitflare.com/customer/v2/licenses

可选择升级到 Bearer 令牌认证（设备流程或钱包签名）以提高安全性。详见认证端点。

端点映射

许可证

v1 端点	v2 等价
`GET /customer/v1/licenses`	`GET /customer/v2/licenses`
`GET /customer/v1/licenses/{id}`	`GET /customer/v2/licenses/{id}`
`POST /customer/v1/licenses/{id}/reset-key`	`POST /customer/v2/licenses/{id}/reset-key`
`POST /customer/v1/licenses/{id}/regenerate-key`	`POST /customer/v2/licenses/{id}/regenerate-key`
`GET /customer/v1/locations`	`GET /customer/v2/licenses/locations`
`GET /customer/v1/licenses/{id}/ips`	`GET /customer/v2/licenses/{id}/ips`
`POST /customer/v1/licenses/{id}/ips`	`POST /customer/v2/licenses/{id}/ips`
`DELETE /customer/v1/licenses/{id}/ips/{ip}`	`DELETE /customer/v2/licenses/{id}/ips/{ip}`

仅 v2 新增

这些端点在 v1 中不存在，仅在 v2 中可用：

端点	说明
`POST /customer/v2/auth/device/code`	启动设备授权流程
`POST /customer/v2/auth/device/token`	用设备码换取访问令牌
`POST /customer/v2/auth/wallet/challenge`	请求钱包签名质询
`POST /customer/v2/auth/wallet/verify`	验证钱包签名并获取令牌
`GET /customer/v2/api-keys`	列出全部 API 密钥
`POST /customer/v2/api-keys`	创建新 API 密钥
`PATCH /customer/v2/api-keys/{id}`	更新 API 密钥
`DELETE /customer/v2/api-keys/{id}`	删除 API 密钥
`GET /customer/v2/profile`	获取用户资料
`PATCH /customer/v2/profile`	更新用户资料
`GET /customer/v2/profile/balance`	获取账户余额
`GET /customer/v2/invoices`	列出发票
`GET /customer/v2/invoices/{id}`	获取指定发票
`POST /customer/v2/invoices/{id}/pay`	使用账户余额支付发票

迁移步骤

更新基础 URL

将客户端路径前缀从 /customer/v1/ 改为 /customer/v2/：

# Before
curl -H "X-ORBIT-KEY: YOUR_API_KEY" \
  https://api.orbitflare.com/customer/v1/licenses

# After
curl -H "X-ORBIT-KEY: YOUR_API_KEY" \
  https://api.orbitflare.com/customer/v2/licenses

更新 locations 端点

locations 端点从顶层路径移至 licenses 组：

# Before
GET /customer/v1/locations

# After
GET /customer/v2/licenses/locations

测试集成

在 v2 端点上运行现有集成。共享端点（许可证、IP）的响应形状向后兼容。已迁移端点通常无需修改响应解析。

（可选）升级认证

若希望使用 Bearer 令牌而非 API 密钥，请实现设备授权流程或钱包签名流程。

需要帮助？

迁移中遇到问题，请在 Discord 联系或发邮件至 support@orbitflare.com。

概览

客户 API v2

客户 API v1（已弃用）

变更内容

身份验证 — 无需变更

端点映射

许可证

仅 v2 新增

迁移步骤

需要帮助？

​变更内容

​身份验证 — 无需变更

​端点映射

​许可证

​仅 v2 新增

​迁移步骤

​需要帮助？

变更内容

身份验证 — 无需变更

端点映射

许可证

仅 v2 新增

迁移步骤

需要帮助？