Definition
如何向护照 API 进行认证？
您的系统通过 HTTPS 出示按环境、按能力签发的限定范围持有者密钥。读取受限护照层级的第三方则完全不使用密钥：他们出示由访问策略所信任的一方签发的 W3C 可验证凭证，解析器则返回该凭证所对应的层级。
The separation matters because the two have different lifecycles. A key belongs to your integration and rotates on your schedule; a credential belongs to a recycler or an authority and is revoked when their permit lapses, not when your contract does.
请求
出示密钥
curl https://api.circuleid.com/v1/passports/01/09506000134352 \
-H "Authorization: Bearer $CIRCULEID_API_KEY"
# Scope errors are explicit rather than a bare 403:
# {
# "error": "insufficient_scope",
# "required": "passports:read:restricted",
# "granted": ["passports:read:public", "events:write"]
# }对比
密钥与凭证对照
| API key | Verifiable credential | |
|---|---|---|
| Authenticates | Your systems | A third party reading a passport |
| Issued by | CirculeID, to your organisation | A party the access policy trusts |
| Scoped by | Environment and capability | What the credential asserts |
| Revoked when | You rotate or a key leaks | A permit or accreditation lapses |
| Verified by | Us, on each request | Anyone, cryptographically |
| Lives in | Your secret manager | The holder’s own wallet or system |
实践做法
我们的建议
每个服务一把密钥
这样一来，泄露的影响半径可以用一句话说清楚。
最小权限作用域
签发流水线从不需要对受限层级的读取权限。
环境隔离
按设计，沙箱密钥无法触及生产环境的护照。
带重叠期的轮换
更换期间两把密钥同时有效，因此密钥轮换不会变成一场发布竞速。
尽可能短生命周期
为短生命周期负载所用的密钥设置有效期，可限制一次泄露持续产生影响的时间。
先核查，再假定
日志显示某个密钥在有效期内做了什么——这是判断暴露面的依据。
答疑
常见问题
这里所说的 API 密钥与凭证有什么区别？
API 密钥用于向 CirculeID 认证贵方系统，其权限限定在贵组织可执行的范围内。可验证凭证则用于向护照认证第三方 —— 回收商、维修方、主管机关 —— 并决定其所获得的层级。密钥由我们签发；凭证来自访问策略所信任的一方。
密钥的作用域应如何设定？
范围要窄，并按服务划分。签发流水线只需要对护照的写入权限，此外一概不需要；店面只需要对公开层级的读取权限，此外一概不需要。按能力限定作用域意味着：某个服务的密钥即便泄露，也不会暴露另一个服务所持有的受限数据。
沙箱密钥与生产密钥可以互换吗？
不能，这是刻意为之。密钥自带环境属性，因此沙箱密钥无法触及生产环境的护照，生产密钥也不会被误用在测试装置里。护照是长期存在的公开产物；生产环境中的误签发，并不是可以悄悄删掉的东西。
密钥轮换如何处理？
密钥可以重叠：先签发新密钥、完成部署，再吊销旧密钥，期间两者同时有效。没有重叠窗口的轮换等于一场发布竞速，而组织往往因此干脆不再轮换。
如果密钥泄露会怎样？
请立即吊销；吊销在下一次请求时即生效，而不是等到缓存过期。审计日志会显示该密钥在有效期内做过什么 —— 这正是您判断影响范围所需要的，也正是把密钥作用域收窄能让这一判断变得简短的原因。