Cobre 的 身份认证 API 支持安全、无摩擦地访问 Cobre Move Money 平台。使用从 Cobre 门户获取的 user_id 和 secret 进行身份认证，即可在后续所有 API 调用中获得短期有效的 JSON Web Token（JWT）。

Cobre 身份认证 API 指南

Cobre 身份认证 API 支持在 Cobre Money Movement 平台内进行安全交互。请按照以下逐步指南完成身份认证并有效使用平台服务。

获取 API 凭据

在进行身份认证之前，您需要获取必要的 API 凭据：user_id 和 secret。这些凭据在 Cobre 生态系统内提供，确保以安全且简便的方式访问平台。

登录平台

准备好 API 凭据后，使用它们登录平台。向身份认证 API 端点发送请求，并附带您的 user_id 和 secret。认证成功后，API 将返回一个 JSON Web Token（JWT）。

认证请求示例：

POST /auth
Content-Type: application/json

{
  "user_id": "your_user_id",
  "secret": "your_secret"
}

认证响应示例：

{
    "access_token": "eyJhbGciOiJSUzI1...",
    "type": "Bearer",
    "expiration_time": 1200
}

开始资金流动！

获得 JWT token 后，您即可开始所有资金流动操作。

登录缓存与 token 生命周期

Cobre 在服务端缓存登录 token。当您使用相同凭据调用身份认证端点时，Cobre 会在签发新 token 之前先检查缓存：

Cache hit — 返回已缓存的 token；不会生成新的 JWT。

Cache miss — 生成新 token 并将其存入缓存。

缓存 TTL 为 token 有效期的 90%。这会形成一个 10% 的安全缓冲期：JWT 仍然有效，但缓存已过期，因此下一次登录调用始终会获取新 token，而不是返回接近过期的 token。

生产环境中 token 有效期目前为 1 200 秒（20 分钟）。该值可能会变更；以下所有比例关系适用于任意 expiration_time。

各场景下 `expiration_time` 的含义

场景	响应中的 `expiration_time`
Cache miss（首次调用，或缓存 TTL 过期后）	token 完整有效期（例如 1 200 秒）
Cache hit（0 < T < 缓存 TTL）	缓存剩余 TTL — 而非 JWT 的剩余有效期

在 cache hit 场景下，应将 expiration_time 视为距离应刷新时间的剩余时长 — 而非 JWT 的绝对过期时间。例如：在 T + 1 分钟时，您可能收到 1 020 秒，尽管底层 JWT 是在更早时间签发的。

参数	值（20 分钟 token 示例）
Token 有效期	1 200 秒（20 分钟）
缓存 TTL（90%）	1 080 秒（18 分钟）
10% 安全缓冲	120 秒（2 分钟）— token 仍有效，缓存已失效
推荐的客户端刷新时机（95%）	1 140 秒（19 分钟）

Token 管理最佳实践

Cobre API 使用短期有效的访问 token，因此您的集成必须以受控方式处理 token 刷新：

不要在每次 API 调用时都请求新 token。 这样做效率低下，且可能因频率限制而导致您被封禁。

缓存 token，重复使用，并仅在 token 接近过期时才进行刷新。

实现一个统一的 token 管理器，供所有 Cobre API 请求共用。

这样可以实现：

更低的延迟（减少认证调用次数）

更稳定的吞吐量

更清晰的错误处理和可观测性

在高负载下更强的弹性

建议

在客户端缓存 token 并重复使用，直到 expiration_time 到期 — 切勿在每次请求时都调用 /v1/auth。

在 expiration_time 的 95% 时刷新（20 分钟 token 对应 1 140 秒 / 19 分钟）。服务端缓存于 90%（18 分钟）过期，因此在 95% 时调用始终发生在缓存过期之后 — 可保证获取新 token。

同一组凭据在多个 worker 之间共享一个 token — 并行调用可复用同一缓存条目。

尽可能将 token 存储在内存中（速度最快）。如果您运行多个实例，请考虑使用共享缓存（如 Redis、Memcached），以便所有副本复用同一 token。

参考实现（语言无关的伪代码）

在每次向 Cobre 发起请求之前，使用以下逻辑：

function getValidToken():
  refresh_at = cached_expires_at - (0.05 * cached_expiration_time)

  if cached_token exists AND now < refresh_at:
      return cached_token

  lock(token_refresh_lock):
      # Double-check after acquiring lock
      if cached_token exists AND now < refresh_at:
          return cached_token

      response = requestNewToken()
      cached_token = response.access_token
      cached_expiration_time = response.expiration_time
      cached_expires_at = now + response.expiration_time
      return cached_token

如果您的系统存在并行请求，请使用锁或互斥量确保每次只有一个刷新操作执行，其余请求等待其完成。这可避免 token 风暴 — 高负载下多个 token 刷新操作同时进行。

处理 401 响应

在 Cobre 任何 API 端点上收到 401，表示 Authorization: Bearer <access_token> 请求头缺失、格式错误，或 token 已过期或不再有效 —— 这与 403（token 有效但对该资源权限不足）不同。

如果您遵循上述 95% 刷新策略，401 应该很少出现。请将其视为后备保障机制，而不是主要的 token 管理策略。

推荐处理方式：

收到 401 时，使用您的 user_id/secret 重新调用 POST /auth 获取新 token。

使用新 token 仅重试一次原始请求。

如果重试仍返回 401，请停止重试 —— 这表示凭据无效（而非 token 过期），应作为需要人工检查 user_id/secret 的严重故障上报。

对于非幂等请求（例如创建 Money Movement），刷新 token 后重试时，请务必配合**幂等键（idempotency key）**使用。如果原始请求在响应到达您这边之前已被 Cobre 处理，盲目重试可能会造成重复操作。重试时请复用相同的幂等键。

response = call(endpoint, token)
if response.status == 401:
    token = requestNewToken()
    response = call(endpoint, token, idempotency_key=same_key)
    if response.status == 401:
        raise AuthenticationError("Invalid credentials")

身份认证允许的操作

🔑 身份认证

描述： 使用 user_id 和 secret 换取短期有效的 Bearer token。

操作后的预期结果： 返回包含 access_token、type 和 expiration_time 的 JWT。

📘 了解更多：

🔗 身份认证

如何开始

在开始之前，我们建议您先了解使用本方案所需的前置步骤。

在门户中创建 API 凭据

访问门户，在左侧菜单底部找到 Developers 部分。

进入 Developers 部分后，点击 API 凭据选项卡，然后点击 + Create Credential。

弹出新窗口后，为凭据指定别名并选择角色，以创建具有所需访问权限的 API 凭据。

凭据生成后，请务必将其保存在安全的地方，因为之后将无法再次获取。

使用此 API 后的预期结果

在所有 Cobre API 调用中使用 JWT

在后续每次 Cobre API 请求中，通过 Authorization: Bearer <access_token> 请求头传递 token。

根据 expiration_time 缓存并刷新

保存 token 及其过期时间戳。复用缓存 token，直到达到 Token 管理最佳实践 中描述的 95% 刷新点 — 不要为每次业务 API 调用都请求新 token。

继续阅读其他 API 指南

请查看后续章节，了解更多 Cobre API 信息并开始集成资金流动流程。

了解我们的身份认证 API 技术文档：

身份认证 API

获取身份认证 token，开始使用 Cobre API

身份验证

Cobre 身份认证 API 指南#

登录缓存与 token 生命周期#

各场景下 expiration_time 的含义#

Token 管理最佳实践#

建议#

参考实现（语言无关的伪代码）#

处理 401 响应#

身份认证允许的操作#

如何开始#

使用此 API 后的预期结果#

Cobre 身份认证 API 指南

登录缓存与 token 生命周期

各场景下 `expiration_time` 的含义

Token 管理最佳实践

建议

参考实现（语言无关的伪代码）

处理 401 响应

身份认证允许的操作

如何开始

使用此 API 后的预期结果