跳转到主要内容

凭证配置

Quick Reference

What了解和管理 A55 API（应用程序编程接口）凭证
Why正确的凭证管理可防止安全事件和集成故障
Reading Time8 分钟
Difficulty初级
Prerequisites沙箱或生产环境账户

凭证类型​

凭证格式用途
entity_uuidUUID（通用唯一标识符）v4在 A55 中标识您的业务实体
merchant_uuidUUID v4标识特定的商户配置
client_idString用于认证的 OAuth2（开放授权）客户端标识符
client_secretStringOAuth2 客户端密钥——请务必保密
wallet_uuidUUID v4标识包含收款记录的 wallet（钱包）

层级结构​

实体 (entity_uuid)
└── 商户 (merchant_uuid)
    ├── 钱包 A (wallet_uuid)
    │   ├── 收款 1
    │   └── 收款 2
    └── 钱包 B (wallet_uuid)
        └── 收款 3

单个实体（entity）可以拥有多个商户（例如不同的业务线），每个商户可以拥有多个钱包。

沙箱 vs 生产环境​

方面沙箱生产环境
API 基础 URLhttps://sandbox.api.a55.techhttps://api.a55.tech
认证 URLhttps://auth.sandbox.a55.techhttps://auth.a55.tech
Cognito 池独立池独立池
凭证不同的 client_id/client_secret不同的 client_id/client_secret
真实资金否是
测试卡接受拒绝
凭证不可互换

沙箱凭证无法在生产环境中使用，反之亦然。每个环境拥有独立的 Cognito 用户池，配有单独的 client_id 和 client_secret。

如何轮换凭证​

  1. 联系 tech.services@a55.tech 申请凭证轮换
  2. A55 生成新的 client_secret，同时保持 client_id 不变
  3. 新旧 client_secret 在 24 小时过渡期内均有效
  4. 更新您的环境变量并部署
  5. 确认新 client_secret 可正常使用后，通知 A55 吊销旧 client_secret
# 收到新凭证后
export A55_CLIENT_SECRET="new_rotated_secret_value"

# 验证认证是否正常
curl -s -X POST "https://auth.sandbox.a55.tech/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=${A55_CLIENT_ID}" \
  -d "client_secret=${A55_CLIENT_SECRET}" \
  -d "scope=api/readwrite" | python3 -m json.tool

安全最佳实践​

永远不要将密钥提交到版本控制系统​

# 将以下内容加入 .gitignore
.env
.env.local
.env.production

使用环境变量​

# .env（仅用于本地开发——切勿提交此文件）
A55_CLIENT_ID=your_client_id
A55_CLIENT_SECRET=your_client_secret

# 在您的应用程序中
import os
client_id = os.environ["A55_CLIENT_ID"]

每 90 天轮换一次​

设置日历提醒。凭证轮换可限制密钥泄露后的影响范围。

限制访问权限​

  • 只有后端服务才应有权访问 client_secret
  • 永远不要在前端代码、日志或错误消息中暴露凭证
  • 使用云提供商的密钥管理服务（AWS Secrets Manager、Azure Key Vault、GCP Secret Manager）

监控使用情况​

  • 在日志中跟踪令牌签发情况
  • 对认证失败设置告警——这可能表明凭证已泄露或被吊销
  • 每月审查 API 访问模式

A55 使用 OAuth2 client_credentials 授权类型，专为机器到机器（M2M）认证设计：

  1. 您的服务器将 client_id + client_secret 发送到令牌端点
  2. A55 的 Cognito 返回一个有效期为 3600 秒（1 小时）的 JWT（JSON Web Token）访问令牌
  3. 您在每个 API 请求中以 Authorization: Bearer <token> 的形式携带此令牌
  4. 在令牌过期前，您的代码必须请求新令牌

没有用户交互、没有授权码、没有重定向——这是一种适用于后端服务的直接凭证交换方式。

令牌结构： JWT 包含您的 entity_uuid、授权范围和过期时间。您可以解码它（base64 编码），但无需这样做——直接将其传递给 API 即可。

快速入门 →使用您的凭证发起一笔收款认证 →令牌生命周期和刷新流程上线检查清单 →验证生产就绪状态