Autenticación

La API Voki utiliza autenticación basada en JWT (JSON Web Tokens) con soporte para MFA (Multi-Factor Authentication) vía TOTP. Todos los endpoints autenticados requieren el header Authorization con el token y X-Tenant con el slug del tenant.

Headers Obligatorios

Header	Descripción	Ejemplo
Authorization	Token JWT de acceso	Bearer eyJhbGci...
X-Tenant	Slug del tenant	avanter
Content-Type	Tipo del contenido	application/json

Endpoints

Método	Endpoint	Descripción
POST	/api/auth/login	Login con email y contraseña
POST	/api/auth/refresh	Renovar token de acceso
POST	/api/auth/mfa/verify	Verificar código MFA
POST	/api/auth/logout	Cerrar sesión

---

Login

Autentica a un usuario y devuelve tokens JWT.

POST /api/auth/login

Request Body

Campo	Tipo	Obligatorio	Descripción
email	string	Sí	Email del usuario
password	string	Sí	Contraseña del usuario
tenant	string	Sí	Slug del tenant

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

Respuesta Exitosa (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
    }
  }
}

Respuesta con MFA Activado (200)

Cuando el usuario tiene MFA habilitado, el login devuelve un token parcial que requiere verificación MFA:

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

Errores

Código	Descripción
401	Credenciales inválidas
422	Campos obligatorios ausentes
429	Rate limit excedido (máx. 5/min)

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

---

Verificar MFA

Completa el flujo de autenticación cuando MFA está activado.

POST /api/auth/mfa/verify

Request Body

Campo	Tipo	Obligatorio	Descripción
mfa_token	string	Sí	Token temporal recibido en el login
code	string	Sí	Código TOTP de 6 dígitos

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

Respuesta Exitosa (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
    }
  }
}

Errores

Código	Descripción
401	Código MFA inválido o expirado
422	Campos obligatorios ausentes

---

Refresh Token

Renueva el token de acceso usando el refresh token.

POST /api/auth/refresh

Request Body

Campo	Tipo	Obligatorio	Descripción
refresh_token	string	Sí	Refresh token recibido en el login

Ejemplo de Request

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

Respuesta Exitosa (200)

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

Errores

Código	Descripción
401	Refresh token inválido o expirado

---

Logout

Invalida el token de acceso actual.

POST /api/auth/logout

Ejemplo de Request

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

Respuesta Exitosa (200)

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

---

Flujo de Autenticación

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

Roles

Rol	Nivel	Permisos
attendant	1	Atender llamadas, gestionar clientes
supervisor	2	Todo de attendant + gestionar departamentos y sectores
manager	3	Todo de supervisor + gestionar usuarios, empresa, facturación y analytics