Authentication

The Voki API uses JWT (JSON Web Tokens) based authentication with MFA (Multi-Factor Authentication) support via TOTP. All authenticated endpoints require the Authorization header with the token and X-Tenant with the tenant slug.

Required Headers

Header	Description	Example
Authorization	JWT access token	Bearer eyJhbGci...
X-Tenant	Tenant slug	avanter
Content-Type	Content type	application/json

Endpoints

Method	Endpoint	Description
POST	/api/auth/login	Login with email and password
POST	/api/auth/refresh	Renew access token
POST	/api/auth/mfa/verify	Verify MFA code
POST	/api/auth/logout	End session

---

Login

Authenticates a user and returns JWT tokens.

POST /api/auth/login

Request Body

Field	Type	Required	Description
email	string	Yes	User email
password	string	Yes	User password
tenant	string	Yes	Tenant slug

Request Example

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

Success Response (200)

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

Response with MFA Enabled (200)

When the user has MFA enabled, the login returns a partial token that requires MFA verification:

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

Errors

Code	Description
401	Invalid credentials
422	Missing required fields
429	Rate limit exceeded (max 5/min)

{
  "errors": {
    "detail": "Invalid credentials"
  }
}

---

Verify MFA

Completes the authentication flow when MFA is enabled.

POST /api/auth/mfa/verify

Request Body

Field	Type	Required	Description
mfa_token	string	Yes	Temporary token received during login
code	string	Yes	6-digit TOTP code

Request Example

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

Success Response (200)

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

Errors

Code	Description
401	Invalid or expired MFA code
422	Missing required fields

---

Refresh Token

Renews the access token using the refresh token.

POST /api/auth/refresh

Request Body

Field	Type	Required	Description
refresh_token	string	Yes	Refresh token received during login

Request Example

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

Success Response (200)

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

Errors

Code	Description
401	Invalid or expired refresh token

---

Logout

Invalidates the current access token.

POST /api/auth/logout

Request Example

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

Success Response (200)

{
  "data": {
    "message": "Session ended successfully"
  }
}

---

Authentication Flow

┌─────────────┐     POST /auth/login     ┌──────────────┐
│   Client     │ ──────────────────────── │   Server     │
│             │                          │              │
│             │ ◄── 200 + tokens ─────── │              │  (without MFA)
│             │                          │              │
│             │ ◄── 200 + mfa_token ──── │              │  (with MFA)
│             │                          │              │
│             │  POST /auth/mfa/verify   │              │
│             │ ──────────────────────── │              │
│             │ ◄── 200 + tokens ─────── │              │
│             │                          │              │
│             │  GET /api/v1/users       │              │
│             │  + Authorization header  │              │
│             │  + X-Tenant header       │              │
│             │ ──────────────────────── │              │
│             │ ◄── 200 + data ──────── │              │
└─────────────┘                          └──────────────┘

Roles

Role	Level	Permissions
attendant	1	Handle calls, manage customers
supervisor	2	Everything from attendant + manage departments and sectors
manager	3	Everything from supervisor + manage users, company, billing, and analytics