Autenticação

A API Voki utiliza autenticação baseada em JWT (JSON Web Tokens) com suporte a MFA (Multi-Factor Authentication) via TOTP. Todos os endpoints autenticados requerem o header Authorization com o token e X-Tenant com o slug do tenant.

Headers Obrigatórios

Header	Descrição	Exemplo
Authorization	Token JWT de acesso	Bearer eyJhbGci...
X-Tenant	Slug do tenant	avanter
Content-Type	Tipo do conteúdo	application/json

Endpoints

Método	Endpoint	Descrição
POST	/api/auth/login	Login com email e senha
POST	/api/auth/refresh	Renovar token de acesso
POST	/api/auth/mfa/verify	Verificar código MFA
POST	/api/auth/logout	Encerrar sessão

---

Login

Autentica um usuário e retorna tokens JWT.

POST /api/auth/login

Request Body

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	Email do usuário
password	string	Sim	Senha do usuário
tenant	string	Sim	Slug do tenant

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@empresa.com",
    "password": "senhaSegura123",
    "tenant": "avanter"
  }'

Resposta de Sucesso (200)

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Admin",
      "email": "admin@empresa.com",
      "role": "manager",
      "avatar_url": null,
      "mfa_enabled": false
    }
  }
}

Resposta com MFA Ativado (200)

Quando o usuário tem MFA habilitado, o login retorna um token parcial que requer verificação MFA:

{
  "data": {
    "mfa_required": true,
    "mfa_token": "temp_token_for_mfa_verification..."
  }
}

Erros

Código	Descrição
401	Credenciais inválidas
422	Campos obrigatórios ausentes
429	Rate limit excedido (máx. 5/min)

{
  "errors": {
    "detail": "Credenciais inválidas"
  }
}

---

Verificar MFA

Completa o fluxo de autenticação quando MFA está ativado.

POST /api/auth/mfa/verify

Request Body

Campo	Tipo	Obrigatório	Descrição
mfa_token	string	Sim	Token temporário recebido no login
code	string	Sim	Código TOTP de 6 dígitos

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "temp_token_for_mfa_verification...",
    "code": "123456"
  }'

Resposta de Sucesso (200)

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Admin",
      "email": "admin@empresa.com",
      "role": "manager",
      "avatar_url": null,
      "mfa_enabled": true
    }
  }
}

Erros

Código	Descrição
401	Código MFA inválido ou expirado
422	Campos obrigatórios ausentes

---

Refresh Token

Renova o token de acesso usando o refresh token.

POST /api/auth/refresh

Request Body

Campo	Tipo	Obrigatório	Descrição
refresh_token	string	Sim	Refresh token recebido no login

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Resposta de Sucesso (200)

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Erros

Código	Descrição
401	Refresh token inválido ou expirado

---

Logout

Invalida o token de acesso atual.

POST /api/auth/logout

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/auth/logout \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": {
    "message": "Sessão encerrada com sucesso"
  }
}

---

Fluxo de Autenticação

┌─────────────┐     POST /auth/login     ┌──────────────┐
│   Cliente    │ ──────────────────────── │   Servidor   │
│             │                          │              │
│             │ ◄── 200 + tokens ─────── │              │  (sem MFA)
│             │                          │              │
│             │ ◄── 200 + mfa_token ──── │              │  (com MFA)
│             │                          │              │
│             │  POST /auth/mfa/verify   │              │
│             │ ──────────────────────── │              │
│             │ ◄── 200 + tokens ─────── │              │
│             │                          │              │
│             │  GET /api/v1/users       │              │
│             │  + Authorization header  │              │
│             │  + X-Tenant header       │              │
│             │ ──────────────────────── │              │
│             │ ◄── 200 + data ──────── │              │
└─────────────┘                          └──────────────┘

Roles (Papéis)

Role	Nível	Permissões
attendant	1	Atender chamadas, gerenciar clientes
supervisor	2	Tudo de attendant + gerenciar departamentos e setores
manager	3	Tudo de supervisor + gerenciar usuários, empresa, billing e analytics