接入说明

适用对象: 拟接入本平台身份认证与人脸比对接口的第三方平台、黄弢工作团队内部系统、黄弢志愿者指导中心相关系统
版本: V1.0  更新日期: 2026年11月6日

本说明用于指导接入方完成从申请到调用的全流程。涉及合规义务与责任划分的内容,以《黄弢统一身份认证平台接入规范》为准;涉及字段、地址、限额的具体取值,以平台控制台与技术文档的最新版本为准。

一、接入前需要了解的事

本平台是身份认证与人脸比对的能力提供方,实名认证与人脸核验均由平台在自身认证流程中完成,接入方不自行采集人脸图像、不自行开展比对,只调用核验结果。

这意味着接入方的工作量主要集中在三件事上:

  1. 在业务系统中放置入口,引导用户前往本平台完成注册与认证;
  2. 用户完成认证后,凭平台返回的标识调用接口获取认证结果;
  3. 按权限范围使用结果,不超范围留存与使用数据。

平台侧的处理方式: 用户人脸录入时,平台提取面部特征并仅保存其加密数学表示,不保存人脸照片;原始图像在特征提取完成后即行删除。接入方获得的返回内容中不包含面部特征数据,也不包含任何人脸图像。

二、接入流程总览

步骤事项责任方产出
1提交接入申请,说明业务场景与拟调用的接口接入方申请记录
2确认接入,开通接口权限平台权限范围与调用配额
3在「API 密钥管理」中生成 API 密钥平台 / 接入方API 密钥
4按本说明完成联调接入方联调通过
5上线运行,按规范使用与留存数据接入方—

三、申请接入

向平台提交接入申请,至少说明以下内容:

  • 接入方主体信息:名称、联系人、联系方式;
  • 业务场景:在什么业务环节、为解决什么问题需要核验身份,该场景是否具有特定目的和充分必要性;
  • 拟调用的接口:从第四章接口清单中选择;
  • 预估调用量:日均调用次数与峰值,便于平台分配配额;
  • 用户引导方式:用户在接入方系统中通过什么入口前往本平台认证。

平台确认后开通接口权限,并告知可调用的接口范围与权限等级。平台保留基于安全或合规原因拒绝、限制或暂停接入的权利。

四、接口清单

接口用途说明
认证结果查询查询指定用户是否已在本平台完成实名认证及认证状态用于业务前置校验,判断用户是否具备进入下一步的条件
人脸比对核验发起一次人脸比对核验并获取核验结论用于关键业务环节的身份确认;接入方通过相机采集用户面部图像并提交,平台与用户已录入的面部特征进行比对并返回核验结论。图像仅用于本次比对,接入方不得留存。
密钥状态查询查询当前 API 密钥的可用状态与配额使用情况便于接入方做异常监控与容量预警

各接口的实际路径、请求方法与字段以平台「接口文档」为准。

五、调用方式

所有 API 请求必须在 HTTP 请求头中携带 API 密钥。

密钥在平台「API 密钥管理」中生成和管理。同一次请求使用一种方式即可,无需同时携带。

密钥使用要求

  • 密钥只在服务端使用,不得写入前端页面、移动端包体或公开代码仓库;
  • 密钥不得转交、转售或以任何形式提供给未获平台接入许可的第三方;
  • 建议按环境(测试 / 生产)分别做好密钥的管理,避免混用;
  • 发现密钥泄露或存在异常调用时,立即向平台报告;
  • 平台有权基于安全风险停用已泄露的密钥。