适用对象: 拟接入本平台身份认证与人脸比对接口的第三方平台、黄弢工作团队内部系统、黄弢志愿者指导中心相关系统
版本: V1.0 更新日期: 2026年11月6日
本说明用于指导接入方完成从申请到调用的全流程。涉及合规义务与责任划分的内容,以《黄弢统一身份认证平台接入规范》为准;涉及字段、地址、限额的具体取值,以平台控制台与技术文档的最新版本为准。
一、接入前需要了解的事
本平台是身份认证与人脸比对的能力提供方,实名认证与人脸核验均由平台在自身认证流程中完成,接入方不自行采集人脸图像、不自行开展比对,只调用核验结果。
这意味着接入方的工作量主要集中在三件事上:
- 在业务系统中放置入口,引导用户前往本平台完成注册与认证;
- 用户完成认证后,凭平台返回的标识调用接口获取认证结果;
- 按权限范围使用结果,不超范围留存与使用数据。
平台侧的处理方式: 用户人脸录入时,平台提取面部特征并仅保存其加密数学表示,不保存人脸照片;原始图像在特征提取完成后即行删除。接入方获得的返回内容中不包含面部特征数据,也不包含任何人脸图像。
二、接入流程总览
| 步骤 | 事项 | 责任方 | 产出 |
|---|---|---|---|
| 1 | 提交接入申请,说明业务场景与拟调用的接口 | 接入方 | 申请记录 |
| 2 | 确认接入,开通接口权限 | 平台 | 权限范围与调用配额 |
| 3 | 在「API 密钥管理」中生成 API 密钥 | 平台 / 接入方 | API 密钥 |
| 4 | 按本说明完成联调 | 接入方 | 联调通过 |
| 5 | 上线运行,按规范使用与留存数据 | 接入方 | — |
三、申请接入
向平台提交接入申请,至少说明以下内容:
- 接入方主体信息:名称、联系人、联系方式;
- 业务场景:在什么业务环节、为解决什么问题需要核验身份,该场景是否具有特定目的和充分必要性;
- 拟调用的接口:从第四章接口清单中选择;
- 预估调用量:日均调用次数与峰值,便于平台分配配额;
- 用户引导方式:用户在接入方系统中通过什么入口前往本平台认证。
平台确认后开通接口权限,并告知可调用的接口范围与权限等级。平台保留基于安全或合规原因拒绝、限制或暂停接入的权利。
四、接口清单
| 接口 | 用途 | 说明 |
|---|---|---|
| 认证结果查询 | 查询指定用户是否已在本平台完成实名认证及认证状态 | 用于业务前置校验,判断用户是否具备进入下一步的条件 |
| 人脸比对核验 | 发起一次人脸比对核验并获取核验结论 | 用于关键业务环节的身份确认;接入方通过相机采集用户面部图像并提交,平台与用户已录入的面部特征进行比对并返回核验结论。图像仅用于本次比对,接入方不得留存。 |
| 密钥状态查询 | 查询当前 API 密钥的可用状态与配额使用情况 | 便于接入方做异常监控与容量预警 |
各接口的实际路径、请求方法与字段以平台「接口文档」为准。
五、调用方式
所有 API 请求必须在 HTTP 请求头中携带 API 密钥。
密钥在平台「API 密钥管理」中生成和管理。同一次请求使用一种方式即可,无需同时携带。
密钥使用要求
- 密钥只在服务端使用,不得写入前端页面、移动端包体或公开代码仓库;
- 密钥不得转交、转售或以任何形式提供给未获平台接入许可的第三方;
- 建议按环境(测试 / 生产)分别做好密钥的管理,避免混用;
- 发现密钥泄露或存在异常调用时,立即向平台报告;
- 平台有权基于安全风险停用已泄露的密钥。