---
title: 身份验证
description: 如何在 Human Dashboard 中进行身份验证、设置您的组织，并生成每个 Human Token API 请求中使用的 x-unico-accesskey。
canonical: https://developer.unico.io/zh-CN/human-token/get-started/authentication
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- 开始使用
- 身份验证

**本页内容# 身份验证

本指南将引导您在 Human Dashboard 中完成身份验证，并生成您将在所有 Human Token API 请求中使用的 `x-unico-accesskey`。
该流程分为两个阶段：

**身份验证** — 完成登录并获取访问令牌。提供两种身份验证方式：

**生物识别登录** — 通过 Unico SDK 进行人脸采集（注册和登录均可使用）
**邮箱 OTP 登录** — 将一次性验证码发送到已注册的邮箱地址（仅限登录）

**设置您的组织** — 创建您的公司资料并生成访问密钥（仅限首次注册）

### 设置凭据的两种方式​

本指南中的所有操作也可以通过 **Human Dashboard**（[dashboard.unico.app](https://dashboard.unico.app)）完成 — 无  需调用 API。
方式适用场景**Dashboard**首次设置、手动轮换密钥、偶尔的管理操作**API**自动化配置、CI/CD 流水线、以编程方式管理密钥
#### 使用 Dashboard​

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

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

本页中的所有端点均由 Human Dashboard API 提供。Human Token API 请求（例如 Create Process 和 Get Process）发送到 [环境](/zh-CN/human-token/get-started/environments) 中列出的 API 主机。
环境API基础 URLProductionHuman Dashboard API（登录、组织、访问密钥和分支）`https://api.humantoken.unico.app`
### 身份验证方式​

提供两种方式进行身份验证并获取 `authToken`：
方式端点适用场景**生物识别**`POST /api/console/v1/auth/biometric/sessions`注册（新账号）或登录（回访用户）**邮箱 OTP**`POST /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": "admin@acme.com",    "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` 进入终止状态。
`status``outcome`含义`pending``pending`用户尚未完成采集 — 继续轮询`processing``pending`采集已完成，正在计算结果 — 继续轮询`completed``matched`登录成功 — 响应中包含 `authToken``completed``no_match`生物识别未匹配任何记录`completed``inconclusive`采集成功，但无法得出结论`expired`—链接已过期 — 从步骤 1 重新开始`canceled`—会话已取消 — 从步骤 1 重新开始
**轮询会话时返回的其他与意图相关的错误：**
HTTP条件`400`**SIGNUP** — 生物识别身份已注册（重复账号）`400`**SIGNIN** — 生物识别身份未注册（账号不存在）
成功响应：
```
{  "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": "admin@acme.com"  }'
```

备注该邮箱必须属于已存在的账号。如果未找到账号，步骤 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`）`400`OTP 已被使用、已达到最大尝试次数或已过期`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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 三字母代码（例如 `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": "admin@acme.com",    "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": "admin@acme.com",    "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": "admin@acme.com",    "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": "admin@acme.com",    "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` 请求都将自动使用与其关联的分支配置。最后更新 于 2026年10月21日**