Autenticação

Markdown

Este guia mostra como se autenticar no Human Dashboard e gerar a x-unico-accesskey que você vai usar em todas as requisições à API do Human Token.

O fluxo tem duas fases:

Autenticar — conclua um login e obtenha um token de acesso. Há dois métodos de autenticação disponíveis:
- Login biométrico — captura facial pelo Unico SDK (disponível para cadastro e para login)
- Login por OTP de email — código de uso único enviado ao endereço de email cadastrado (somente login)
Configurar sua organização — crie o perfil da sua empresa e gere uma access key (somente no primeiro cadastro)

Duas formas de configurar suas credenciais

Tudo o que está neste guia também pode ser feito pelo Human Dashboard, em dashboard.unico.app — sem nenhuma chamada de API.

Opção	Quando usar
Dashboard	Configuração inicial, rotação manual de chaves, gestão ocasional
API	Provisionamento automatizado, pipelines de CI/CD, gestão programática de chaves

Usando o dashboard

Acesse dashboard.unico.app
Cadastre-se ou faça login — use o login biométrico (captura facial) ou o OTP de email
Crie sua organização — preencha o nome da empresa, o país e os domínios permitidos
Gere uma access key — vá em Access Keys e clique em Create key; copie a chave imediatamente, ela é exibida apenas uma vez
Gerencie as branches — crie e configure branches em Branches; cada branch gera a própria access key

A access key obtida no dashboard é a mesma x-unico-accesskey usada em todas as requisições à API — as duas abordagens são totalmente intercambiáveis.

URLs base

Todos os endpoints desta página são servidos pela Human Dashboard API. As requisições à API do Human Token, como Create Process e Get Process, vão para o host da API listado em Ambientes.

Ambiente	API	URL base
Produção	Human Dashboard API (login, organização, access keys e branches)	`https://api.humantoken.unico.app`

Métodos de autenticação

Há dois métodos disponíveis para se autenticar e obter um authToken:

Método	Endpoint	Quando usar
Biométrico	`POST /api/console/v1/auth/biometric/sessions`	Cadastro (nova conta) ou login (usuário que já tem conta)
OTP de email	`POST /api/console/v1/auth/email/sessions`	Somente login — a conta já precisa existir

Toda chamada a POST /api/console/v1/auth/biometric/sessions precisa declarar um intent:

`intent`	Quando usar	Campo `email`	Campo `name`
`LOGIN_INTENT_SIGNUP`	Primeiro cadastro — criação de uma nova conta	Obrigatório	Obrigatório
`LOGIN_INTENT_SIGNIN`	Usuário que já tem conta — a conta já existe	Não usado	Não usado
(omitido)	Tratado como `LOGIN_INTENT_SIGNIN`	Não usado	Não usado

O intent controla a validação feita quando você consulta a sessão (Passo 2):

SIGNUP — rejeita o login se essa identidade biométrica já estiver cadastrada (evita contas duplicadas).
SIGNIN — rejeita o login se essa identidade biométrica não estiver cadastrada (a conta precisa existir para fazer login).

Fase 1 — Autenticar

SIGNUP (primeiro cadastro)

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

Unicidade do email

Se já houver uma conta cadastrada com esse email, a requisição retorna 400 Bad Request.

Resposta:

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

No SIGNUP, os campos link e token vêm vazios na resposta — o link de captura biométrica é enviado para o endereço de email informado.

SIGNIN (usuário que já tem conta)

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

Resposta:

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

Guarde o sessionId.

SIGNUP: o link de captura biométrica é enviado para o email informado no Passo 1. Peça ao usuário que verifique a caixa de entrada e conclua a captura.
SIGNIN: abra o link no navegador e conclua a captura biométrica.

Passo 2: Consulte até a sessão ser resolvida

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

Consulte a cada 2–3 segundos até o status chegar a um estado terminal.

`status`	`outcome`	Significado
`pending`	`pending`	O usuário ainda não concluiu a captura — continue consultando
`processing`	`pending`	Captura concluída, resultados em processamento — continue consultando
`completed`	`matched`	Login bem-sucedido — o `authToken` está presente
`completed`	`no_match`	A biometria não correspondeu a nenhum registro
`completed`	`inconclusive`	A captura foi bem-sucedida, mas não pôde ser resolvida
`expired`	—	O link expirou — recomece pelo Passo 1
`canceled`	—	A sessão foi cancelada — recomece pelo Passo 1

Erros adicionais, específicos de cada intent, ao consultar a sessão:

HTTP	Condição
`400`	SIGNUP — a identidade biométrica já está cadastrada (conta duplicada)
`400`	SIGNIN — a identidade biométrica não está cadastrada (a conta não existe)

Resposta de sucesso:

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

Guarde o authToken — use-o como header x-console-authorization em todas as requisições seguintes à Human Dashboard API.

Use este fluxo em vez do biométrico se o usuário já tiver uma conta e preferir se autenticar com um código de uso único enviado ao email cadastrado. O cadastro não é suportado por OTP de email — use o fluxo biométrico no primeiro cadastro.

Passo 1: Envie o OTP

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

observação

O email precisa pertencer a uma conta existente. Se nenhuma conta for encontrada, o Passo 2 (validar o OTP) retorna 404 Not Found.

Resposta:

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

Guarde o sessionId. Um código de 6 dígitos é enviado para o endereço de email informado.

Passo 2: Valide o OTP

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

HTTP	Condição
`200`	Código válido — o `authToken` está presente
`400`	Código incorreto (`invalid otp code`)
`400`	OTP já usado, número máximo de tentativas atingido ou expirado
`404`	Email não cadastrado

Resposta de sucesso:

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

Guarde o authToken — use-o como header x-console-authorization em todas as requisições seguintes à Human Dashboard API.

Fase 2 — Configure sua organização

Passo 3: Crie sua organização

observação

Esta chamada só pode ser feita uma vez. Ela provisiona seu tenant e gera seu branchId.

Qualquer país é aceito. Use o código de três letras ISO 3166-1 alpha-3 (ex.: BRA, USA, MEX, DEU, IND). O taxId é opcional para todos os 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"]
  }'

Resposta:

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

Guarde o branchId — ele identifica sua branch padrão e é usado na gestão de branches e de access keys.

Passo 4: Crie uma access key

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

Resposta:

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

aviso

A accessKey é retornada apenas uma vez e não pode ser recuperada depois. Armazene-a imediatamente no seu gerenciador de segredos como HUMAN_TOKEN_ACCESS_KEY.

Esse valor é o header x-unico-accesskey usado em todas as requisições à API do Human Token.

O que você tem agora

Valor	Onde usar
`branchId`	Identificar sua branch padrão; criar access keys específicas de uma branch
`accessKey`	Header `x-unico-accesskey` em todas as requisições do Human Token

Gerenciando sua organização

Consultar a organização

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

Resposta:

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

Atualizar a organização

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

Gerenciando access keys

Listar chaves (somente metadados — o segredo nunca é retornado):

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

Fazer a rotação de uma chave (a chave antiga é invalidada imediatamente):

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

Revogar uma chave (irreversível):

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

Gerenciando branches

As branches permitem segmentar a configuração da sua organização (nome, logo, domínios permitidos) por produto ou ambiente. Cada branch tem as próprias access keys, então o contexto da branch é resolvido automaticamente a partir da chave usada na requisição — não é preciso enviar o branchId no CreateProcess.

Criar uma branch

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

Resposta:

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

Guarde o branchId — use-o ao criar uma access key específica da branch.

Atualizar uma branch

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

Criar uma access key específica de uma branch

Para gerar uma access key restrita a uma branch específica, inclua o branchId no corpo da requisição:

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

Resposta:

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

aviso

A accessKey é retornada apenas uma vez. Armazene-a imediatamente. Toda requisição de CreateProcess autenticada com essa chave usa automaticamente a configuração da branch associada a ela.

Duas formas de configurar suas credenciais​

Usando o dashboard​

URLs base​

Métodos de autenticação​

Intent do login biométrico​

Fase 1 — Autenticar​

Passo 1: Inicie uma sessão de login biométrico​

Passo 2: Consulte até a sessão ser resolvida​

Fase 1 (alternativa) — Login por OTP de email​

Passo 1: Envie o OTP​

Passo 2: Valide o OTP​

Fase 2 — Configure sua organização​

Passo 3: Crie sua organização​

Passo 4: Crie uma access key​

O que você tem agora​

Gerenciando sua organização​

Consultar a organização​

Atualizar a organização​

Gerenciando access keys​

Gerenciando branches​

Criar uma branch​

Atualizar uma branch​

Criar uma access key específica de uma branch​

Duas formas de configurar suas credenciais

Usando o dashboard

URLs base

Métodos de autenticação

Intent do login biométrico

Fase 1 — Autenticar

Passo 1: Inicie uma sessão de login biométrico

Passo 2: Consulte até a sessão ser resolvida

Fase 1 (alternativa) — Login por OTP de email

Passo 1: Envie o OTP

Passo 2: Valide o OTP

Fase 2 — Configure sua organização

Passo 3: Crie sua organização

Passo 4: Crie uma access key

O que você tem agora

Gerenciando sua organização

Consultar a organização

Atualizar a organização

Gerenciando access keys

Gerenciando branches

Criar uma branch

Atualizar uma branch

Criar uma access key específica de uma branch