API Utilisateurs

Objectif

Gérer les utilisateurs côté backoffice et exposer le contexte utilisateur authentifié sans donner aux frontends la logique RBAC.

Périmètre

Consultation, mise à jour administrative et gestion de rôles globaux.

Acteurs/applications consommatrices

• Backoffice DMV.
• API Laravel.
• Support/admin global.

Authentification requise

Routes admin visibles : identify.app, auth:sanctum, ensure.admin.

Permissions/RBAC

• Réservé aux administrateurs globaux.
• Les rôles acteur restent à gérer via les pivots métier, pas uniquement via l’utilisateur.

Endpoints actuels visibles si confirmés

Méthode	Route	Statut
GET	/api/v1/admin/users	Confirmé.
GET	/api/v1/admin/users/{userId}	Confirmé.
PATCH	/api/v1/admin/users/{userId}	Confirmé.
POST	/api/v1/admin/users/{userId}/roles	Confirmé.
DELETE	/api/v1/admin/users/{userId}/roles/{role}	Confirmé.

Endpoints cibles proposés si utile

• GET /api/v1/users/me pourrait être un alias cible, mais /auth/me existe déjà.
• Aucun remplacement proposé sans arbitrage.

Exemple de requête

GET /api/v1/admin/users?page=1
Authorization: Bearer <admin-token>
X-App-Source: backoffice

Exemple de réponse succès

{
  "data": [
    {
      "user_id": "user-id",
      "email": "utilisateur@example.test",
      "roles": ["admin"],
      "status": "active"
    }
  ],
  "meta": {
    "page": 1
  }
}

Exemple d’erreur

{
  "error": "forbidden",
  "message": "Droits administrateur requis."
}

Pagination si applicable

Applicable sur la liste utilisateurs.

Rate limiting si applicable

Recommandé sur les opérations de rôles et recherche support.

Audit/logs si applicable

Obligatoire pour attribution/retrait de rôles, suspension ou modification sensible.

Sécurité

• Ne pas exposer de secrets, tokens ou données provider.
• Minimiser les données personnelles affichées dans le backoffice.

État actuel vs cible

Sujet	État actuel	Cible
Backoffice users	Routes admin visibles.	Contrat de payload et audit stabilisés.
RBAC	ensure.admin visible.	Matrice complète rôle + scope.

Points à confirmer

• Champs modifiables.
• Liste officielle des rôles globaux.
• Politique RGPD d’export/suppression.