API d’Authentification

L’Authentication API gère tous les flux de vérification d’identité : login email/mot de passe, signup, refresh des tokens, magic link, authentification à deux facteurs et le flux d’autorisation OAuth2. Les endpoints publics ne nécessitent pas de header Authorization ; les endpoints utilisateur et admin oui.

Email / Mot de Passe

POST/api/auth/login

Authentifie un utilisateur avec email et mot de passe. Retourne un access token, refresh token, ID de session et expiration du token. Si le tenant ou l’application exige le 2FA et que l’utilisateur a configuré le 2FA, la réponse indiquera qu’un second facteur est requis avant l’émission des tokens.

Corps de la requête


{
  "email": "[email protected]",
  "password": "secret123"
}

Réponse de succès (2FA non requise)


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_abc123",
    "tokenType": "Bearer"
  }
}

Réponse de succès (2FA requise)


{
  "ok": true,
  "data": {
    "requiresTwoFactor": true,
    "sessionId": "sess_abc123",
    "availableMethods": ["totp", "sms"]
  }
}

Codes d’erreur

Code	HTTP	Description
`INVALID_CREDENTIALS`	401	Email ou mot de passe incorrect
`ACCOUNT_LOCKED`	403	Compte bloqué pour trop de tentatives échouées
`ACCOUNT_DISABLED`	403	Compte désactivé par un administrateur
`RATE_LIMITED`	429	Trop de tentatives de login

POST/api/auth/signup

Enregistre un nouveau compte utilisateur. Le tenant doit avoir le signup activé. En cas de succès, retourne la même structure token que le login. Si le tenant exige la vérification email, un email est envoyé et l’utilisateur ne peut pas se connecter avant la vérification.

Corps de la requête


{
  "email": "[email protected]",
  "password": "motdepassesecurise",
  "firstName": "Alice",
  "lastName": "Dupont"
}

firstName et lastName sont optionnels. password est obligatoire sauf si le tenant est configuré uniquement pour le signup passwordless.

Réponse de succès


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_xyz789",
    "tokenType": "Bearer"
  }
}

Codes d’erreur

Code	HTTP	Description
`EMAIL_TAKEN`	409	Un compte avec cet email existe déjà
`SIGNUP_DISABLED`	403	Le tenant a désactivé le signup public
`WEAK_PASSWORD`	400	Le mot de passe ne satisfait pas les exigences de robustesse
`VALIDATION_ERROR`	400	Le corps de la requête n’a pas passé la validation du schéma

Endpoint Token (OAuth2)

POST/api/auth/token

Endpoint token OAuth2. Supporte plusieurs grant types : Authorization Code (avec PKCE), Client Credentials (M2M) et Device Code. La structure du corps de la requête diffère selon le grant type.

Cet endpoint est l’endpoint token OAuth2 standard référencé dans le document de discovery OIDC. Il accepte les corps de requête application/json ou application/x-www-form-urlencoded.

Grant : Authorization Code + PKCE

Utilisé pour échanger un code d’autorisation (depuis le redirect du hosted login) avec des tokens. Le code_verifier est la valeur aléatoire originale depuis laquelle le code_challenge a été dérivé.

Corps de la requête


{
  "grant_type": "authorization_code",
  "code": "code_auth_depuis_redirect",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "redirect_uri": "https://app.votredomaine.com/callback",
  "client_id": "votre-client-id"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "idToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codes d’erreur

Code	HTTP	Description
`CODE_INVALID`	400	Le code d’autorisation n’existe pas ou est expiré
`CODE_USED`	400	Le code d’autorisation a déjà été échangé (usage unique)
`PKCE_MISMATCH`	400	`SHA256(code_verifier)` ne correspond pas au challenge stocké
`REDIRECT_URI_MISMATCH`	400	`redirect_uri` ne correspond pas à l’URI enregistré

Grant : Client Credentials (M2M)

Utilisé pour l’authentification machine-to-machine où aucun utilisateur n’est impliqué. Le client s’authentifie avec client_id et client_secret.

Corps de la requête


{
  "grant_type": "client_credentials",
  "client_id": "m2m-client-id",
  "client_secret": "m2m-client-secret",
  "scope": "read:users manage:roles"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "scope": "read:users manage:roles"
  }
}

Grant : Device Code (RFC 8628)

Utilisé pour les appareils qui ne peuvent pas afficher un navigateur (CLI, IoT, Smart TV). D’abord l’appareil demande un device code ; l’utilisateur visite ensuite l’URL de vérification sur un appareil séparé et approuve. L’appareil poll jusqu’à approbation.

Corps de la requête (polling)


{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "votre-client-id"
}

Réponse en attente (l’utilisateur n’a pas encore approuvé)


{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "L'utilisateur n'a pas encore approuvé la demande. Continue le polling."
  }
}

Gestion des Tokens

POST/api/auth/refresh

Échange un refresh token pour un nouveau access token et un nouveau refresh token. Les refresh tokens sont tournés à chaque utilisation — l’ancien refresh token est immédiatement invalidé.

Corps de la requête


{
  "refreshToken": "rt_..."
}

Réponse de succès


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_nouveau...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codes d’erreur

Code	HTTP	Description
`REFRESH_TOKEN_INVALID`	401	Le token n’existe pas ou a été révoqué
`REFRESH_TOKEN_EXPIRED`	401	Le token a dépassé son délai d’expiration

POST/api/auth/validateRequires: authenticated user

Valide l’access token courant et retourne les informations de l’utilisateur authentifié. Cet endpoint est aussi l’endpoint UserInfo OIDC.

Requête : Aucun corps requis. L’access token est lu depuis le header Authorization: Bearer.

Réponse de succès


{
  "ok": true,
  "data": {
    "valid": true,
    "userId": "usr_abc123",
    "email": "[email protected]",
    "username": "alice.dupont",
    "firstName": "Alice",
    "lastName": "Dupont",
    "roles": ["viewer", "billing-admin"],
    "tenant": "acme-corp"
  }
}

POST/api/auth/logoutRequires: authenticated user

Invalide la session courante. Le refresh token associé à la session est révoqué. L’access token continue d’être valide jusqu’à son expiration naturelle (les JWT ne sont pas mis en blocklist par défaut — fie-toi aux courtes durées d’expiration).

Requête : Aucun corps requis.

Réponse de succès


{
  "ok": true,
  "data": { "loggedOut": true }
}

Magic Link (Passwordless)

POST/api/auth/magic-link

Envoie un magic link (email de login passwordless) à l’adresse spécifiée. Si aucun compte n’existe et allowSignup est activé dans la configuration passwordless du tenant, un nouveau compte est créé automatiquement quand le lien est cliqué.

Corps de la requête


{
  "email": "[email protected]",
  "redirectUrl": "https://app.votredomaine.com/callback"
}

redirectUrl est optionnel ; il utilise comme fallback l’URL de redirect par défaut configuré dans le tenant.

Réponse de succès


{
  "ok": true,
  "data": { "sent": true }
}

La réponse est toujours { sent: true } indépendamment du fait que l’email existe, pour prévenir l’énumération des utilisateurs.

POST/api/auth/magic-link/verify

Vérifie un token magic link. Appelé automatiquement par la page hosted login quand l’utilisateur clique le lien. Retourne les tokens en cas de succès.

Corps de la requête


{
  "token": "mlnk_..."
}

Réponse de succès


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codes d’erreur

Code	HTTP	Description
`MAGIC_LINK_INVALID`	400	Le token est malformé ou n’existe pas
`MAGIC_LINK_EXPIRED`	400	Le token est expiré (expiration par défaut : 15 minutes)
`MAGIC_LINK_USED`	400	Le token a déjà été consommé (usage unique)

Réinitialisation du Mot de Passe

POST/api/auth/forgot-password

Initie un flux de réinitialisation du mot de passe. Envoie un email avec un lien de réinitialisation à l’adresse spécifiée. La réponse est toujours positive pour prévenir l’énumération des utilisateurs.

Corps de la requête


{
  "email": "[email protected]"
}

Réponse de succès


{
  "ok": true,
  "data": { "sent": true }
}

Authentification à Deux Facteurs

POST/api/auth/verify-2fa

Vérifie un second facteur après l’authentification initiale par mot de passe. Appelle cet endpoint avec l’ID de session retourné par le login (quand requiresTwoFactor: true) et le code OTP ou la réponse WebAuthn. En cas de succès, retourne les access et refresh tokens complets.

Corps de la requête — TOTP


{
  "sessionId": "sess_abc123",
  "code": "123456",
  "method": "totp"
}

Corps de la requête — SMS OTP


{
  "sessionId": "sess_abc123",
  "code": "789012",
  "method": "sms"
}

Corps de la requête — WebAuthn


{
  "sessionId": "sess_abc123",
  "method": "webauthn",
  "response": { }
}

response est l’objet AuthenticatorAssertionResponse de l’API WebAuthn du navigateur.

Réponse de succès


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codes d’erreur

Code	HTTP	Description
`INVALID_OTP`	400	Le code fourni est incorrect
`OTP_EXPIRED`	400	Le code est expiré
`SESSION_INVALID`	400	L’ID de session n’est pas valide ou a déjà été consommé
`WEBAUTHN_FAILED`	400	La vérification de l’assertion WebAuthn a échoué

GET/api/auth/check-2fa-requiredRequires: authenticated user

Vérifie si la session courante nécessite la vérification 2FA avant que l’accès complet soit accordé. Utile pour protéger les pages après le login initial pour s’assurer que l’utilisateur a complété le flux complet.

Réponse


{
  "ok": true,
  "data": {
    "required": false,
    "verified": true,
    "availableMethods": ["totp", "sms"]
  }
}

Détection SSO

POST/api/auth/sso/detect

Détecte si le domaine email d’un utilisateur a une connexion Enterprise SSO configurée. Utilise-le pour implémenter des formulaires de login “intelligents” qui redirigent automatiquement les utilisateurs enterprise vers leur provider SSO au lieu d’afficher le champ mot de passe.

Corps de la requête


{
  "email": "[email protected]"
}

Réponse — SSO disponible


{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/enterprise-alias"
  }
}

Réponse — aucun SSO


{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

Endpoint d’Autorisation OAuth2

POST/api/oauth/authorize

Initie un flux OAuth2 Authorization Code + PKCE. Cet endpoint crée une session et redirige l’utilisateur vers la page hosted login d’Auris. Après une authentification réussie, Auris redirige vers le redirect_uri enregistré avec un code d’autorisation.

Cet endpoint est typiquement déclenché comme redirect du navigateur (GET ou form POST) plutôt que comme appel fetch. La méthode SDK loginWithRedirect() gère tout cela automatiquement.

Paramètres (query string ou corps de la requête)

Paramètre	Obligatoire	Description
`response_type`	Oui	Doit être `"code"`
`client_id`	Oui	Client ID de l’Application
`redirect_uri`	Oui	URL de callback (doit être enregistré)
`state`	Oui	Token CSRF aléatoire
`code_challenge`	Oui	BASE64URL(SHA256(code_verifier))
`code_challenge_method`	Oui	Doit être `"S256"`
`scope`	Non	Scopes séparés par espaces (ex. `openid profile email`)
`login_hint`	Non	Pré-remplit le champ email
`screen_hint`	Non	`"signup"` pour afficher d’abord l’écran d’inscription
`locale`	Non	Force un locale spécifique (`en`, `it`, `de`, `fr`, `es`)
`prompt`	Non	`"login"` pour forcer la ré-authentification

Redirect en cas de succès


https://app.votredomaine.com/callback?code=code_auth_xxx&state=state_original

Redirect en cas d’erreur


https://app.votredomaine.com/callback?error=access_denied&error_description=Utilisateur+a+annulé&state=state_original

Codes d’erreur (retournés comme paramètres de redirect)

Code	Description
`invalid_request`	Paramètre manquant ou invalide
`unauthorized_client`	`client_id` non trouvé ou `redirect_uri` non enregistré
`access_denied`	L’utilisateur a annulé l’authentification
`invalid_scope`	Le scope demandé n’est pas autorisé

Pages Associées

OAuth 2.0 & OIDC — Fondements du protocole derrière les endpoints d’authentification
Les Tokens Expliqués — Access token, refresh token et ID token en détail
Flux PKCE — Comment fonctionne l’échange Authorization Code + PKCE
Guide Hosted Login — Intègre le hosted login avec ton application
Magic Link — Authentification email passwordless
Social Login — Configure des providers d’identité tiers
Credentials M2M Client — Authentification serveur-à-serveur
Paramètres Authentification — Configure MFA, passwordless et social login dans la Console