Autenticación

Markdown

Esta guía te acompaña en la autenticación en el Human Dashboard y en la generación de la x-unico-accesskey que usarás en todas las solicitudes a la API de Human Token.

El flujo tiene dos fases:

Autenticarse — completa un inicio de sesión y obtén un token de acceso. Hay dos métodos de autenticación disponibles:
- Inicio de sesión biométrico — captura facial mediante el Unico SDK (disponible tanto para registro como para inicio de sesión)
- Inicio de sesión con OTP por email — código de un solo uso enviado a la dirección de email registrada (solo inicio de sesión)
Configurar tu organización — crea el perfil de tu empresa y genera una clave de acceso (solo en el primer registro)

Dos formas de configurar tus credenciales

Todo lo que se describe en esta guía también se puede hacer a través del Human Dashboard en dashboard.unico.app — sin necesidad de llamadas a la API.

Opción	Cuándo usarla
Dashboard	Configuración inicial, rotación manual de claves, gestión ocasional
API	Aprovisionamiento automatizado, pipelines de CI/CD, gestión programática de claves

Uso del dashboard

Ve a dashboard.unico.app
Regístrate o inicia sesión — usa el inicio de sesión biométrico (captura facial) o el OTP por email
Crea tu organización — completa el nombre de tu empresa, el país y los dominios permitidos
Genera una clave de acceso — ve a Access Keys y haz clic en Create key; cópiala de inmediato, solo se muestra una vez
Gestiona las sucursales — crea y configura sucursales en Branches; cada sucursal genera su propia clave de acceso

La clave de acceso que obtienes en el dashboard es la misma x-unico-accesskey utilizada en todas las solicitudes a la API — ambos enfoques son totalmente intercambiables.

URL base

Todos los endpoints de esta página los sirve la Human Dashboard API. Las solicitudes a la API de Human Token, como Create Process y Get Process, van al host de la API indicado en Entornos.

Entorno	API	URL base
Producción	Human Dashboard API (inicio de sesión, organización, claves de acceso y sucursales)	`https://api.humantoken.unico.app`

Métodos de autenticación

Hay dos métodos disponibles para autenticarte y obtener un authToken:

Método	Endpoint	Cuándo usarlo
Biométrico	`POST /api/console/v1/auth/biometric/sessions`	Registro (cuenta nueva) o inicio de sesión (usuario recurrente)
OTP por email	`POST /api/console/v1/auth/email/sessions`	Solo inicio de sesión — la cuenta ya debe existir

Intent del inicio de sesión biométrico

Cada llamada a POST /api/console/v1/auth/biometric/sessions debe declarar un intent:

`intent`	Cuándo usarlo	Campo `email`	Campo `name`
`LOGIN_INTENT_SIGNUP`	Primer registro — creación de una cuenta nueva	Obligatorio	Obligatorio
`LOGIN_INTENT_SIGNIN`	Usuario recurrente — la cuenta ya existe	No se usa	No se usa
(omitido)	Se trata como `LOGIN_INTENT_SIGNIN`	No se usa	No se usa

El intent controla la validación que se hace al consultar la sesión (Paso 2):

SIGNUP — rechaza el inicio de sesión si esa identidad biométrica ya está registrada (evita cuentas duplicadas).
SIGNIN — rechaza el inicio de sesión si esa identidad biométrica no está registrada (la cuenta debe existir para iniciar sesión).

Fase 1 — Autenticarse

Paso 1: Iniciar una sesión de inicio de sesión biométrico

SIGNUP (primer registro)

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

Unicidad del email

Si ya hay una cuenta registrada con ese email, la solicitud devuelve 400 Bad Request.

Respuesta:

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

En SIGNUP, los campos link y token vienen vacíos en la respuesta — el enlace de captura biométrica se envía a la dirección de email proporcionada.

SIGNIN (usuario recurrente)

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

Respuesta:

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

Guarda el sessionId.

SIGNUP: el enlace de captura biométrica se envía al email proporcionado en el Paso 1. Pide al usuario que revise su bandeja de entrada y complete la captura.
SIGNIN: abre link en tu navegador y completa la captura biométrica.

Paso 2: Consultar hasta que la sesión se resuelva

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

Consulta cada 2–3 segundos hasta que status alcance un estado terminal.

`status`	`outcome`	Significado
`pending`	`pending`	El usuario aún no completó la captura — sigue consultando
`processing`	`pending`	Captura realizada, resultados en cálculo — sigue consultando
`completed`	`matched`	Inicio de sesión exitoso — `authToken` está presente
`completed`	`no_match`	La biometría no coincidió con ningún registro
`completed`	`inconclusive`	La captura fue exitosa, pero no se pudo resolver
`expired`	—	El enlace expiró — reinicia desde el Paso 1
`canceled`	—	La sesión fue cancelada — reinicia desde el Paso 1

Errores adicionales específicos del intent al consultar la sesión:

HTTP	Condición
`400`	SIGNUP — la identidad biométrica ya está registrada (cuenta duplicada)
`400`	SIGNIN — la identidad biométrica no está registrada (la cuenta no existe)

Respuesta exitosa:

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

Guarda el authToken — úsalo como header x-console-authorization en todas las solicitudes posteriores a la Human Dashboard API.

Fase 1 (alternativa) — Inicio de sesión con OTP por email

Usa este flujo en lugar del biométrico si el usuario ya tiene una cuenta y prefiere autenticarse mediante un código de un solo uso enviado a su email registrado. El registro no es compatible con el OTP por email — usa el flujo biométrico para el primer registro.

Paso 1: Enviar el OTP

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

nota

El email debe pertenecer a una cuenta existente. Si no se encuentra ninguna cuenta, el Paso 2 (validar el OTP) devuelve 404 Not Found.

Respuesta:

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

Guarda el sessionId. Se envía un código de 6 dígitos a la dirección de email proporcionada.

Paso 2: Validar el OTP

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	Condición
`200`	El código es válido — `authToken` está presente
`400`	El código es incorrecto (`invalid otp code`)
`400`	OTP ya utilizado, máximo de intentos alcanzado o expirado
`404`	Email no registrado

Respuesta exitosa:

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

Guarda el authToken — úsalo como header x-console-authorization en todas las solicitudes posteriores a la Human Dashboard API.

Fase 2 — Configurar tu organización

Paso 3: Crear tu organización

nota

Esta llamada solo se puede hacer una vez. Aprovisiona tu tenant y genera tu branchId.

Se acepta cualquier país. Usa el código de tres letras ISO 3166-1 alpha-3 (por ejemplo, BRA, USA, MEX, DEU, IND). taxId es opcional para todos los países.

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

Respuesta:

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

Guarda el branchId — identifica tu sucursal predeterminada y se usa al gestionar sucursales y claves de acceso.

Paso 4: Crear una clave de acceso

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

Respuesta:

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

advertencia

El accessKey se devuelve una sola vez y no se puede recuperar de nuevo. Almacénalo de inmediato en tu gestor de secretos como HUMAN_TOKEN_ACCESS_KEY.

Este valor es el header x-unico-accesskey utilizado en todas las solicitudes a la API de Human Token.

Lo que tienes ahora

Valor	Dónde usarlo
`branchId`	Identificar tu sucursal predeterminada; crear claves de acceso específicas por sucursal
`accessKey`	Header `x-unico-accesskey` en todas las solicitudes de Human Token

Gestión de tu organización

Obtener la organización

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

Respuesta:

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

Actualizar la organización

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

Gestión de claves de acceso

Listar claves (solo metadatos — el secreto nunca se devuelve):

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

Rotar una clave (la clave anterior se invalida de inmediato):

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

Revocar una clave (irreversible):

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

Gestión de sucursales

Las sucursales te permiten segmentar la configuración de tu organización (nombre, logo, dominios permitidos) por producto o entorno. Cada sucursal tiene sus propias claves de acceso, por lo que el contexto de la sucursal se resuelve automáticamente a partir de la clave usada en la solicitud — no es necesario enviar branchId en CreateProcess.

Crear una sucursal

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

Respuesta:

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

Guarda el branchId — úsalo al crear una clave de acceso específica de la sucursal.

Actualizar una sucursal

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

Crear una clave de acceso específica de la sucursal

Para generar una clave de acceso limitada a una sucursal específica, incluye branchId en el cuerpo de la solicitud:

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

Respuesta:

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

advertencia

El accessKey se devuelve una sola vez. Almacénalo de inmediato. Cualquier solicitud CreateProcess autenticada con esta clave usará automáticamente la configuración de la sucursal asociada a ella.

Dos formas de configurar tus credenciales​

Uso del dashboard​

URL base​

Métodos de autenticación​

Intent del inicio de sesión biométrico​

Fase 1 — Autenticarse​

Paso 1: Iniciar una sesión de inicio de sesión biométrico​

Paso 2: Consultar hasta que la sesión se resuelva​

Fase 1 (alternativa) — Inicio de sesión con OTP por email​

Paso 1: Enviar el OTP​

Paso 2: Validar el OTP​

Fase 2 — Configurar tu organización​

Paso 3: Crear tu organización​

Paso 4: Crear una clave de acceso​

Lo que tienes ahora​

Gestión de tu organización​

Obtener la organización​

Actualizar la organización​

Gestión de claves de acceso​

Gestión de sucursales​

Crear una sucursal​

Actualizar una sucursal​

Crear una clave de acceso específica de la sucursal​

Dos formas de configurar tus credenciales

Uso del dashboard

URL base

Métodos de autenticación

Intent del inicio de sesión biométrico

Fase 1 — Autenticarse

Paso 1: Iniciar una sesión de inicio de sesión biométrico

Paso 2: Consultar hasta que la sesión se resuelva

Fase 1 (alternativa) — Inicio de sesión con OTP por email

Paso 1: Enviar el OTP

Paso 2: Validar el OTP

Fase 2 — Configurar tu organización

Paso 3: Crear tu organización

Paso 4: Crear una clave de acceso

Lo que tienes ahora

Gestión de tu organización

Obtener la organización

Actualizar la organización

Gestión de claves de acceso

Gestión de sucursales

Crear una sucursal

Actualizar una sucursal

Crear una clave de acceso específica de la sucursal