---
title: Autenticação
description: Como se autenticar no Human Dashboard, configurar sua organização e gerar a x-unico-accesskey usada em todas as requisições à API do Human Token.
canonical: https://developer.unico.io/pt-BR/human-token/get-started/authentication
locale: pt-BR
generated_by: markdown-export
---

- [/pt-BR/](/pt-BR/)
- Começar
- Autenticação

**Nesta página# Autenticação

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](https://dashboard.unico.app) — sem nenhuma chamada de API.
OpçãoQuando 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](https://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](/pt-BR/human-token/get-started/environments).
AmbienteAPIURL baseProduçãoHuman 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étodoEndpointQuando 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
### Intent do login biométrico​

Toda chamada a `POST /api/console/v1/auth/biometric/sessions` precisa declarar um `intent`:
`intent`Quando usarCampo `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á existeNão usadoNão usado(omitido)Tratado como `LOGIN_INTENT_SIGNIN`Não usadoNã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​

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

**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": "admin@acme.com",    "name": "Jane Doe"  }'
```

Unicidade do emailSe 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:**
HTTPCondiçã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.
### Fase 1 (alternativa) — Login por OTP de email​

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": "admin@acme.com"  }'
```

observaçãoO 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}
```

HTTPCondiçã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çãoEsta 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) (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": "admin@acme.com",    "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": "admin@acme.com",    "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​

ValorOnde 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": "admin@acme.com",    "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": "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"]  }'
```

### 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.Última atualização em 21 de out. de 2026**