Аутентификация

Markdown

Это руководство описывает, как пройти аутентификацию в Human Dashboard и сгенерировать x-unico-accesskey, который вы будете использовать во всех запросах к API Human Token.

Процесс состоит из двух этапов:

Аутентификация — выполните вход и получите токен доступа. Доступны два способа аутентификации:
- Биометрический вход — захват лица через Unico SDK (доступен как для регистрации, так и для входа)
- Вход по одноразовому коду из email (OTP) — одноразовый код, отправляемый на зарегистрированный адрес электронной почты (только для входа)
Настройка организации — создайте профиль компании и сгенерируйте ключ доступа (только при первой регистрации)

Два способа настроить учётные данные

Всё, что описано в этом руководстве, также можно выполнить через Human Dashboard на dashboard.unico.app — без вызовов API.

Вариант	Когда использовать
Dashboard	Первоначальная настройка, ручная ротация ключей, периодическое управление
API	Автоматическое развёртывание, конвейеры CI/CD, программное управление ключами

Через Dashboard

Перейдите на dashboard.unico.app
Зарегистрируйтесь или войдите — используйте биометрический вход (захват лица) или одноразовый код из email
Создайте организацию — укажите название компании, страну и разрешённые домены
Сгенерируйте ключ доступа — перейдите в раздел Access Keys и нажмите Create key; сразу скопируйте ключ — он отображается только один раз
Управляйте филиалами — создавайте и настраивайте филиалы в разделе Branches; каждый филиал генерирует собственный ключ доступа

Ключ доступа, полученный в Dashboard, — это тот же x-unico-accesskey, который используется во всех запросах к API — оба способа полностью взаимозаменяемы.

Базовые URL

Все эндпоинты на этой странице обслуживаются Human Dashboard API. Запросы к API Human Token, такие как Create Process и Get Process, отправляются на хост API, указанный в разделе Среды.

Среда	API	Базовый URL
Production	Human Dashboard API (вход, организация, ключи доступа и филиалы)	`https://api.humantoken.unico.app`

Способы аутентификации

Для аутентификации и получения authToken доступны два способа:

Способ	Эндпоинт	Когда использовать
Биометрия	`POST /api/console/v1/auth/biometric/sessions`	Регистрация (новый аккаунт) или вход (существующий пользователь)
Email 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": "[email protected]",
    "name": "Jane Doe"
  }'

Уникальность email

Если аккаунт с этим email уже зарегистрирован, запрос возвращает 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: ссылка на биометрический захват отправляется на email, указанный в шаге 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 — используйте его как заголовок x-console-authorization во всех последующих запросах к Human Dashboard API.

Этап 1 (альтернатива) — Вход по одноразовому коду из email

Используйте этот поток вместо биометрического, если у пользователя уже есть аккаунт и он предпочитает аутентифицироваться с помощью одноразового кода, отправленного на зарегистрированный email. Регистрация через email 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]"
  }'

примечание

Email должен принадлежать существующему аккаунту. Если аккаунт не найден, шаг 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`	Email не зарегистрирован

Успешный ответ:

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

Сохраните authToken — используйте его как заголовок x-console-authorization во всех последующих запросах к Human Dashboard API.

Этап 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.

Это значение — заголовок x-unico-accesskey, используемый во всех запросах к API Human Token.

Что у вас теперь есть

Значение	Где использовать
`branchId`	Идентификация филиала по умолчанию; создание ключей доступа для конкретного филиала
`accessKey`	Заголовок `x-unico-accesskey` во всех запросах к Human Token

Управление организацией

Получение организации

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"}'

Управление филиалами

Филиалы позволяют разделять конфигурацию организации (название, логотип, разрешённые домены) по продуктам или средам. У каждого филиала свои ключи доступа, поэтому контекст филиала определяется автоматически по ключу, использованному в запросе, — передавать branchId в CreateProcess не нужно.

Создание филиала

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, аутентифицированный этим ключом, автоматически использует конфигурацию связанного с ним филиала.

Два способа настроить учётные данные​

Через Dashboard​

Базовые URL​

Способы аутентификации​

Намерение биометрического входа​

Этап 1 — Аутентификация​

Шаг 1: Запустите сеанс биометрического входа​

Шаг 2: Опрашивайте, пока сеанс не будет завершён​

Этап 1 (альтернатива) — Вход по одноразовому коду из email​

Шаг 1: Отправьте OTP​

Шаг 2: Проверьте OTP​

Этап 2 — Настройка организации​

Шаг 3: Создайте организацию​

Шаг 4: Создайте ключ доступа​

Что у вас теперь есть​

Управление организацией​

Получение организации​

Обновление организации​

Управление ключами доступа​

Управление филиалами​

Создание филиала​

Обновление филиала​

Создание ключа доступа для конкретного филиала​

Два способа настроить учётные данные

Через Dashboard

Базовые URL

Способы аутентификации

Намерение биометрического входа

Этап 1 — Аутентификация

Шаг 1: Запустите сеанс биометрического входа

Шаг 2: Опрашивайте, пока сеанс не будет завершён

Этап 1 (альтернатива) — Вход по одноразовому коду из email

Шаг 1: Отправьте OTP

Шаг 2: Проверьте OTP

Этап 2 — Настройка организации

Шаг 3: Создайте организацию

Шаг 4: Создайте ключ доступа

Что у вас теперь есть

Управление организацией

Получение организации

Обновление организации

Управление ключами доступа

Управление филиалами

Создание филиала

Обновление филиала

Создание ключа доступа для конкретного филиала