跳转到主要内容

身份验证

Markdown

本指南将引导您在 Human Dashboard 中完成身份验证，并生成您将在所有 Human Token API 请求中使用的 x-unico-accesskey。

该流程分为两个阶段：

  1. 身份验证 — 完成登录并获取访问令牌。提供两种身份验证方式：
    • 生物识别登录 — 通过 Unico SDK 进行人脸采集（注册和登录均可使用）
    • 邮箱 OTP 登录 — 将一次性验证码发送到已注册的邮箱地址（仅限登录）
  2. 设置您的组织 — 创建您的公司资料并生成访问密钥（仅限首次注册）

设置凭据的两种方式​

本指南中的所有操作也可以通过 Human Dashboard（dashboard.unico.app）完成 — 无需调用 API。

方式适用场景
Dashboard首次设置、手动轮换密钥、偶尔的管理操作
API自动化配置、CI/CD 流水线、以编程方式管理密钥

使用 Dashboard​

  1. 访问 dashboard.unico.app
  2. 注册或登录 — 使用生物识别登录（人脸采集）或邮箱 OTP
  3. 创建您的组织 — 填写公司名称、国家和允许的域名
  4. 生成访问密钥 — 进入 Access Keys 并点击 Create key；请立即复制，它仅显示一次
  5. 管理分支 — 在 Branches 下创建和配置分支；每个分支都会生成自己的访问密钥

您从 Dashboard 获取的访问密钥与所有 API 请求中使用的 x-unico-accesskey 相同 — 两种方式完全可以互换。

基础 URL​

本页中的所有端点均由 Human Dashboard API 提供。Human Token API 请求（例如 Create Process 和 Get Process）发送到 环境 中列出的 API 主机。

环境API基础 URL
ProductionHuman Dashboard API（登录、组织、访问密钥和分支）https://api.humantoken.unico.app

身份验证方式​

提供两种方式进行身份验证并获取 authToken：

方式端点适用场景
生物识别POST /api/console/v1/auth/biometric/sessions注册（新账号）或登录（回访用户）
邮箱 OTPPOST /api/console/v1/auth/email/sessions仅限登录 — 账号必须已存在

生物识别登录意图​

每次调用 POST /api/console/v1/auth/biometric/sessions 都必须声明 intent：

intent适用场景email 字段name 字段
LOGIN_INTENT_SIGNUP首次注册 — 创建新账号必填必填
LOGIN_INTENT_SIGNIN回访用户 — 账号已存在不使用不使用
（省略）视为 LOGIN_INTENT_SIGNIN不使用不使用

该意图控制轮询会话时（步骤 2）执行的校验：

  • SIGNUP — 如果该生物识别身份已注册，则拒绝登录（防止重复账号）。
  • SIGNIN — 如果该生物识别身份未注册，则拒绝登录（账号必须存在才能登录）。

阶段 1 — 身份验证​

步骤 1：启动生物识别登录会话​

SIGNUP（首次注册）

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'
邮箱唯一性

如果该邮箱已注册了账号，请求将返回 400 Bad Request。

响应：

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

对于 SIGNUP，响应中的 link 和 token 字段为空 — 生物识别采集链接会发送到所提供的邮箱地址。

SIGNIN（回访用户）

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

响应：

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

保存 sessionId。

  • SIGNUP：生物识别采集链接会发送到步骤 1 中提供的邮箱。请让用户查看收件箱并完成采集。
  • SIGNIN：在浏览器中打开 link 并完成生物识别采集。

步骤 2：轮询直至会话完成​

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

每 2–3 秒轮询一次，直到 status 进入终止状态。

statusoutcome含义
pendingpending用户尚未完成采集 — 继续轮询
processingpending采集已完成，正在计算结果 — 继续轮询
completedmatched登录成功 — 响应中包含 authToken
completedno_match生物识别未匹配任何记录
completedinconclusive采集成功，但无法得出结论
expired—链接已过期 — 从步骤 1 重新开始
canceled—会话已取消 — 从步骤 1 重新开始

轮询会话时返回的其他与意图相关的错误：

HTTP条件
400SIGNUP — 生物识别身份已注册（重复账号）
400SIGNIN — 生物识别身份未注册（账号不存在）

成功响应：

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

保存 authToken — 在后续所有 Human Dashboard API 请求中将其用作 x-console-authorization 请求头。

阶段 1（替代方式）— 邮箱 OTP 登录​

如果用户已有账号，并希望通过发送到其注册邮箱的一次性验证码进行身份验证，请使用此流程代替生物识别。邮箱 OTP 不支持注册 — 首次注册请使用生物识别流程。

步骤 1：发送 OTP​

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
备注

该邮箱必须属于已存在的账号。如果未找到账号，步骤 2（验证 OTP）将返回 404 Not Found。

响应：

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

保存 sessionId。系统会向所提供的邮箱地址发送一个 6 位验证码。

步骤 2：验证 OTP​

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}
HTTP条件
200验证码有效 — 响应中包含 authToken
400验证码错误（invalid otp code）
400OTP 已被使用、已达到最大尝试次数或已过期
404邮箱未注册

成功响应：

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

保存 authToken — 在后续所有 Human Dashboard API 请求中将其用作 x-console-authorization 请求头。

阶段 2 — 设置您的组织​

步骤 3：创建您的组织​

备注

此调用只能执行一次。它会为您开通租户并生成您的 branchId。

接受任何国家。请使用 ISO 3166-1 alpha-3 三字母代码（例如 BRA、USA、MEX、DEU、IND）。对于所有国家，taxId 均为可选。

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

响应：

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

保存 branchId — 它用于标识您的默认分支，并在管理分支和访问密钥时使用。

步骤 4：创建访问密钥​

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

响应：

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}
警告

accessKey 仅返回一次，之后无法再次获取。 请立即将其以 HUMAN_TOKEN_ACCESS_KEY 的名称存入您的密钥管理器。

该值即所有 Human Token API 请求中使用的 x-unico-accesskey 请求头。

您现在拥有的内容​

值用途
branchId标识您的默认分支；创建特定分支的访问密钥
accessKey所有 Human Token 请求中的 x-unico-accesskey 请求头

管理您的组织​

获取组织​

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

响应：

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

更新组织​

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

管理访问密钥​

列出密钥（仅返回元数据 — 绝不会返回密钥本身）：

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

轮换密钥（旧密钥立即失效）：

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

撤销密钥（不可逆）：

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

管理分支​

分支让您可以按产品或环境划分组织的配置（名称、Logo、允许的域名）。每个分支都有自己的访问密钥，因此分支上下文会根据请求中使用的密钥自动解析 — 无需在 CreateProcess 中传入 branchId。

创建分支​

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

响应：

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

保存 branchId — 在创建特定分支的访问密钥时使用它。

更新分支​

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

创建特定分支的访问密钥​

要生成限定于特定分支的访问密钥，请在请求体中包含 branchId：

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

响应：

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}
警告

accessKey 仅返回一次。 请立即存储。使用此密钥进行身份验证的任何 CreateProcess 请求都将自动使用与其关联的分支配置。

最后更新 于