Authentification

L'API Voki utilise une authentification basée sur JWT (JSON Web Tokens) avec support MFA (Multi-Factor Authentication) via TOTP. Tous les endpoints authentifiés nécessitent le header Authorization avec le token et X-Tenant avec le slug du tenant.

Headers Obligatoires

Header	Description	Exemple
Authorization	Token JWT d'accès	Bearer eyJhbGci...
X-Tenant	Slug du tenant	avanter
Content-Type	Type du contenu	application/json

Endpoints

Méthode	Endpoint	Description
POST	/api/auth/login	Connexion avec email et mot de passe
POST	/api/auth/refresh	Renouveler le token d'accès
POST	/api/auth/mfa/verify	Vérifier le code MFA
POST	/api/auth/logout	Fermer la session

---

Connexion

Authentifie un utilisateur et retourne les tokens JWT.

POST /api/auth/login

Request Body

Champ	Type	Obligatoire	Description
email	string	Oui	Email de l'utilisateur
password	string	Oui	Mot de passe de l'utilisateur
tenant	string	Oui	Slug du tenant

Exemple de Requête

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

Réponse de Succès (200)

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

Réponse avec MFA Activé (200)

Lorsque l'utilisateur a le MFA activé, la connexion retourne un token partiel nécessitant une vérification MFA :

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

Erreurs

Code	Description
401	Identifiants invalides
422	Champs obligatoires manquants
429	Rate limit dépassé (max. 5/min)

{
  "errors": {
    "detail": "Identifiants invalides"
  }
}

---

Vérifier le MFA

Complète le flux d'authentification lorsque le MFA est activé.

POST /api/auth/mfa/verify

Request Body

Champ	Type	Obligatoire	Description
mfa_token	string	Oui	Token temporaire reçu lors de la connexion
code	string	Oui	Code TOTP à 6 chiffres

Exemple de Requête

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

Réponse de Succès (200)

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

Erreurs

Code	Description
401	Code MFA invalide ou expiré
422	Champs obligatoires manquants

---

Refresh Token

Renouvelle le token d'accès en utilisant le refresh token.

POST /api/auth/refresh

Request Body

Champ	Type	Obligatoire	Description
refresh_token	string	Oui	Refresh token reçu lors de la connexion

Exemple de Requête

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

Réponse de Succès (200)

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

Erreurs

Code	Description
401	Refresh token invalide ou expiré

---

Déconnexion

Invalide le token d'accès actuel.

POST /api/auth/logout

Exemple de Requête

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

Réponse de Succès (200)

{
  "data": {
    "message": "Session fermée avec succès"
  }
}

---

Flux d'Authentification

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

Rôles

Rôle	Niveau	Permissions
attendant	1	Prendre des appels, gérer les clients
supervisor	2	Tout ce qu'un attendant peut faire + gérer les départements et secteurs
manager	3	Tout ce qu'un supervisor peut faire + gérer les utilisateurs, l'entreprise, la facturation et les analytics