> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comprendre les Autorisations

> Contrôle d'accès basé sur les rôles dans Agatabo

## Aperçu

Agatabo utilise le **contrôle d'accès basé sur les rôles (RBAC)** pour gérer qui peut effectuer quelles actions. Les autorisations sont accordées via des rôles, qui sont assignés aux utilisateurs de l'organisation.

<Note>
  **Fonctionnalités clés** :

  * Les rôles sont propres à chaque organisation (chaque organisation définit ses propres rôles)
  * Les utilisateurs peuvent avoir plusieurs rôles simultanément
  * Les autorisations sont cumulatives (union de tous les rôles assignés)
  * La portée ANY prend le dessus sur la portée SELF lorsque la même autorisation est accordée plusieurs fois
</Note>

***

## Concepts Clés

### Autorisations

Une **autorisation** est la capacité d'effectuer une action spécifique sur une ressource.

**Format** : `resource:action`

**Exemples** :

* `savings:write` - Enregistrer des dépôts et retraits
* `loans:read` - Voir les détails des prêts
* `expenses:write` - Enregistrer des dépenses
* `audit_logs:read` - Voir la piste d'audit

***

### Portées

Chaque autorisation a une **portée** qui détermine quelles données vous pouvez accéder :

| Portée   | Niveau d'Accès                       | Exemple                                       |
| -------- | ------------------------------------ | --------------------------------------------- |
| **SELF** | Uniquement vos propres données       | Voir votre propre solde d'épargne             |
| **ANY**  | Toutes les données de l'organisation | Voir les soldes d'épargne de tous les membres |

**Fonctionnement des portées** :

* `savings:read` avec portée **SELF** : Peut seulement voir son propre solde d'épargne
* `savings:read` avec portée **ANY** : Peut voir les soldes d'épargne de tous les membres
* `loans:write` avec portée **SELF** : Peut seulement demander des prêts pour soi-même
* `loans:write` avec portée **ANY** : Peut créer des prêts pour tout membre

**Priorité des portées** :

* Si un utilisateur a la même autorisation avec différentes portées (via plusieurs rôles), **la portée ANY prend le dessus**
* Exemple : Utilisateur avec `savings:read` SELF via rôle "Membre" + `savings:read` ANY via rôle "Trésorier" = l'utilisateur obtient l'accès **ANY**

***

### Rôles

Un **rôle** est un ensemble d'autorisations assigné à un utilisateur.

**Les rôles sont propres à l'organisation** :

* Chaque organisation définit ses propres rôles
* Les noms de rôles et autorisations sont configurés par les administrateurs
* Aucun rôle global/prédéfini dans le système

**Rôles spéciaux** :

* **admin** : Rôle protégé, ne peut pas être assigné/retiré directement (utiliser l'endpoint set-admin)
* **member** : Lorsqu'il est assigné, crée automatiquement un compte d'épargne du grand livre pour l'utilisateur

**Propriétés d'un rôle** :

* `key` : Identifiant unique (ex. "treasurer", "loan-officer")
* `name` : Nom d'affichage (ex. "Treasurer", "Loan Officer")
* `description` : Description optionnelle de l'objectif du rôle
* `isProtected` : Si true, le rôle ne peut pas être supprimé
* `isEditable` : Si true, les métadonnées et grants du rôle peuvent être modifiés
* `tagColor` : Couleur d'étiquette UI (SLATE, RED, BLUE, GREEN, etc.)

***

## Liste Complète des Autorisations

**Utilisateurs de l'Organisation** (`organization_users`) :

* `organization_users:read` - Voir la liste et les détails des membres
* `organization_users:write` - Ajouter, modifier, retirer des membres
* `organization_user_roles:read` - Voir les définitions de rôles
* `organization_user_roles:write` - Créer, modifier, supprimer les définitions de rôles
* `organization_user_roles:assign` - Assigner/retirer des rôles aux utilisateurs

**Épargne** (`savings`) :

* `savings:read` - Voir l'historique des dépôts/retraits
* `savings:write` - Enregistrer des dépôts et retraits

**Prêts** (`loans`) :

* `loans:read` - Voir les détails de prêts et échéanciers
* `loans:write` - Créer de nouveaux prêts, enregistrer des paiements
* `loans:modify` - Modifier les conditions de prêts existants
* `loans:approve` - Approuver les demandes de prêt

**Comptes Bancaires** (`bank_accounts`) :

* `bank_accounts:read` - Voir la liste et les soldes des comptes bancaires
* `bank_accounts:write` - Créer, mettre à jour, supprimer des comptes bancaires

**Dépenses** (`expenses`) :

* `expenses:read` - Voir l'historique des dépenses
* `expenses:write` - Enregistrer et catégoriser les dépenses

**Actifs** (`assets`) :

* `assets:read` - Voir le registre des immobilisations
* `assets:write` - Ajouter, modifier, céder des actifs

**Réserves** (`reserves`) :

* `reserves:read` - Voir les soldes de réserves
* `reserves:write` - Allouer aux réserves et libérer des réserves

**Dividendes** (`dividends`) :

* `dividends:read` - Voir les bassins et distributions de dividendes
* `dividends:write` - Créer des bassins et distribuer des dividendes

**Grand Livre** (`ledger`) :

* `ledger:read` - Voir les comptes du grand livre, écritures comptables, balance de vérification
* `ledger:write` - Publier des écritures comptables manuelles

**Rapports** (`reports`) :

* `reports:read` - Accéder aux rapports financiers (bilan, compte de résultat, etc.)

**Paramètres** (`settings`) :

* `settings:read` - Voir les paramètres de l'organisation
* `settings:write` - Modifier les paramètres de l'organisation

**Clôture de Période** (`periods`) :

* `periods:close` - Clôturer les périodes comptables

**Piste d'Audit** (`audit_logs`) :

* `audit_logs:read` - Voir la piste d'audit (exige la portée ANY)

***

## Points d'Accès API

### Obtenir Mes Autorisations

**Récupérer vos propres autorisations :**

```http theme={null}
GET /me/permissions
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
```

**Réponse :**

```json theme={null}
{
  "organizationUserId": "orguser-123",
  "roleKeys": ["treasurer", "member"],
  "grants": [
    {
      "permissionKey": "savings:read",
      "scope": "ANY"
    },
    {
      "permissionKey": "savings:write",
      "scope": "ANY"
    },
    {
      "permissionKey": "expenses:write",
      "scope": "ANY"
    }
  ]
}
```

Les **system admins** obtiennent automatiquement toutes les autorisations avec portée ANY.

***

### Lister les Définitions de Rôles

**Obtenir tous les rôles de l'organisation :**

```http theme={null}
GET /role-definitions
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
```

**Autorisation requise** : `organization_user_roles:write`

**Réponse :**

```json theme={null}
[
  {
    "id": "role-123",
    "organizationId": "org-abc",
    "key": "treasurer",
    "name": "Treasurer",
    "description": "Handles deposits and expenses",
    "tagColor": "BLUE",
    "isProtected": false,
    "isEditable": true,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z",
    "grants": [
      {
        "id": "grant-1",
        "roleDefinitionId": "role-123",
        "permissionKey": "savings:write",
        "scope": "ANY",
        "createdAt": "2025-01-15T10:00:00.000Z",
        "updatedAt": "2025-01-15T10:00:00.000Z"
      },
      {
        "id": "grant-2",
        "roleDefinitionId": "role-123",
        "permissionKey": "expenses:write",
        "scope": "ANY",
        "createdAt": "2025-01-15T10:00:00.000Z",
        "updatedAt": "2025-01-15T10:00:00.000Z"
      }
    ],
    "_count": {
      "assignments": 3
    }
  }
]
```

**La réponse inclut** :

* Métadonnées du rôle (key, name, description, couleurs, statut protégé)
* Tous les grants d'autorisation du rôle
* Nombre d'utilisateurs assignés à ce rôle

**Trié par** : Statut protégé (desc), puis key (asc)

***

### Créer une Définition de Rôle

**Créer un nouveau rôle :**

```http theme={null}
POST /role-definitions
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
Body:
{
  "key": "accountant",
  "name": "Accountant",
  "description": "Financial reporting and ledger access",
  "isEditable": true,
  "tagColor": "GREEN"
}
```

**Autorisation requise** : `organization_user_roles:assign`

**Champs du corps de requête** :

| Champ         | Type    | Obligatoire | Description                                           |
| ------------- | ------- | ----------- | ----------------------------------------------------- |
| `key`         | string  | Oui         | Identifiant unique du rôle (minuscules, sans espaces) |
| `name`        | string  | Oui         | Nom d'affichage                                       |
| `description` | string  | Non         | Description du rôle                                   |
| `isEditable`  | boolean | Non         | Le rôle peut-il être modifié ? (défaut : true)        |
| `tagColor`    | string  | Non         | Couleur d'étiquette UI (défaut : "SLATE")             |

**Réponse :**

```json theme={null}
{
  "id": "role-456",
  "organizationId": "org-abc",
  "key": "accountant",
  "name": "Accountant",
  "description": "Financial reporting and ledger access",
  "tagColor": "GREEN",
  "isProtected": false,
  "isEditable": true,
  "createdAt": "2026-06-13T14:00:00.000Z",
  "updatedAt": "2026-06-13T14:00:00.000Z"
}
```

**Remarque** : Un nouveau rôle n'a AUCUNE autorisation par défaut. Utilisez l'endpoint "Mettre à jour les Grants du Rôle" pour ajouter des autorisations.

***

### Mettre à Jour une Définition de Rôle

**Mettre à jour les métadonnées du rôle (nom, description, etc.) :**

```http theme={null}
PUT /role-definitions/{id}
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
Body:
{
  "name": "Senior Accountant",
  "description": "Updated description",
  "tagColor": "BLUE"
}
```

**Autorisation requise** : `organization_user_roles:assign`

**Validation** :

* Le rôle doit exister dans l'organisation
* Le rôle doit avoir `isEditable: true` (les rôles protégés ne peuvent pas être modifiés)

**Réponse** : Objet rôle mis à jour

***

### Mettre à Jour les Grants du Rôle

**Remplacer toutes les autorisations d'un rôle :**

```http theme={null}
PUT /role-definitions/{id}/grants
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
Body:
{
  "grants": [
    {
      "permissionKey": "ledger:read",
      "scope": "ANY"
    },
    {
      "permissionKey": "reports:read",
      "scope": "ANY"
    },
    {
      "permissionKey": "savings:read",
      "scope": "ANY"
    }
  ]
}
```

**Autorisation requise** : `organization_user_roles:assign`

**Fonctionnement** :

1. Supprime TOUS les grants existants de ce rôle
2. Crée les nouveaux grants depuis le corps de requête
3. Retourne le rôle mis à jour avec les nouveaux grants

**Corps de requête** :

| Champ                    | Type   | Obligatoire | Description                             |
| ------------------------ | ------ | ----------- | --------------------------------------- |
| `grants`                 | array  | Oui         | Tableau de grants d'autorisation        |
| `grants[].permissionKey` | string | Oui         | Clé d'autorisation (ex. "savings:read") |
| `grants[].scope`         | enum   | Oui         | "SELF" ou "ANY"                         |

**Un tableau grants vide** retire toutes les autorisations du rôle (autorisé).

**Réponse** : Objet rôle avec grants mis à jour

***

### Supprimer une Définition de Rôle

**Supprimer un rôle :**

```http theme={null}
DELETE /role-definitions/{id}
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
```

**Autorisation requise** : `organization_user_roles:assign`

**Validation** :

* Le rôle doit exister dans l'organisation
* Le rôle ne doit PAS être protégé (`isProtected: false`)

**Ce qui se passe** :

1. Toutes les assignations du rôle sont supprimées (les utilisateurs perdent ce rôle)
2. Tous les grants d'autorisation sont supprimés
3. La définition de rôle est supprimée

**Réponse :**

```json theme={null}
{
  "message": "Role definition deleted successfully"
}
```

**Erreur si rôle protégé** :

```json theme={null}
{
  "message": "Protected role definitions cannot be deleted"
}
```

***

### Assigner un Rôle à un Utilisateur

**Accorder un rôle à un utilisateur de l'organisation :**

```http theme={null}
POST /organization-users/{organizationUserId}/role-assignments
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
Body:
{
  "roleDefinitionId": "role-123",
  "assignedAt": "2026-06-13T00:00:00.000Z"
}
```

**Autorisation requise** : `organization_user_roles:assign`

**Corps de requête** :

| Champ              | Type              | Obligatoire | Description                                |
| ------------------ | ----------------- | ----------- | ------------------------------------------ |
| `roleDefinitionId` | string            | Oui         | ID du rôle à assigner                      |
| `assignedAt`       | string (date ISO) | Non         | Date d'assignation (par défaut maintenant) |

**Comportement spécial** :

* **rôle admin** : Impossible à assigner directement. Utiliser l'endpoint set-admin à la place.
* **rôle member** : Crée automatiquement un compte d'épargne du grand livre pour l'utilisateur

**Réponse :**

```json theme={null}
{
  "id": "assignment-789",
  "organizationUserId": "orguser-123",
  "roleDefinitionId": "role-123",
  "assignedAt": "2026-06-13T00:00:00.000Z",
  "createdAt": "2026-06-13T14:30:00.000Z",
  "updatedAt": "2026-06-13T14:30:00.000Z"
}
```

**Erreurs** :

| Statut | Message                                                 | Cause                              |
| ------ | ------------------------------------------------------- | ---------------------------------- |
| 400    | "Organization user not found"                           | organizationUserId invalide        |
| 400    | "Role definition not found"                             | roleDefinitionId invalide          |
| 403    | "Direct admin assignment is not allowed. Use set-admin" | Tentative d'assigner le rôle admin |

***

### Retirer un Rôle d'un Utilisateur

**Retirer un rôle d'un utilisateur de l'organisation :**

```http theme={null}
DELETE /organization-users/{organizationUserId}/role-assignments/{roleDefinitionId}
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
```

**Autorisation requise** : `organization_user_roles:assign`

**Validation** :

* Impossible de retirer le **rôle admin** directement (utiliser l'endpoint set-admin)

**Réponse** : Nombre de suppressions

**Erreur si rôle admin** :

```json theme={null}
{
  "message": "Direct admin removal is not allowed. Use set-admin"
}
```

***

### Mettre à Jour la Date d'Assignation d'un Rôle

**Changer la date d'assignation d'un rôle :**

```http theme={null}
PATCH /organization-users/{organizationUserId}/role-assignments/{roleDefinitionId}
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
Body:
{
  "assignedAt": "2026-01-01T00:00:00.000Z"
}
```

**Autorisation requise** : `organization_user_roles:assign`

**Cas d'utilisation** : Antidater l'assignation du rôle pour refléter une date d'effet historique

**Réponse** : Objet assignation mis à jour

***

## Comment les Autorisations sont Vérifiées

Lorsque vous effectuez une action dans Agatabo :

1. **Le système vérifie l'authentification** :
   * Jeton d'accès valide requis
   * En-tête x-organization-id requis

2. **Le système vérifie que vous avez l'autorisation requise** :
   * Exemple : enregistrer un dépôt exige `savings:write`
   * L'autorisation est vérifiée contre vos grants effectifs (depuis tous les rôles assignés)

3. **Le système vérifie la portée** :
   * Si l'endpoint précise `requiredScope: "ANY"`, vous devez avoir la portée ANY
   * Si l'endpoint a `scopeParam`, le système vérifie que vous accédez à vos propres données (portée SELF) ou autorise toute donnée (ANY)

4. **Action autorisée ou refusée** :
   * ✓ Autorisée : l'action continue
   * ✗ Refusée : erreur "Insufficient permissions" ou "Permission scope denied"

**Les system admins contournent tous les contrôles** : `userType: "system_admin"` accorde automatiquement toutes les autorisations avec portée ANY.

***

## Logique du Permission Guard

**Depuis permission.guard.ts :**

```typescript theme={null}
// 1. Verify JWT token
const payload = JwtHelper.verifyToken(token, process.env.JWT_SECRET!);

// 2. System admins get ALL permissions
if (payload.userType === 'system_admin') {
  return true; // Bypass permission checks
}

// 3. Resolve organization user
const actor = await organizationUserRbacService.resolveActorOrganizationUser(
  payload.id,
  organizationId
);

// 4. Build effective grants from all assigned roles
const grants = await organizationUserRbacService.buildEffectiveGrants(
  organizationId,
  actor.roles
);

// 5. Check if user has required permission
const grant = organizationUserRbacService.getGrantForPermission(
  grants,
  requirement.key
);

if (!grant) {
  throw new ForbiddenException('Insufficient permissions');
}

// 6. Check required scope (if specified)
if (requirement.options?.requiredScope && grant.scope !== requirement.options.requiredScope) {
  throw new ForbiddenException('Insufficient permission scope');
}

// 7. Check SELF scope restriction (if applicable)
if (grant.scope === 'SELF' && requirement.options?.scopeParam) {
  const targetId = request.params[requirement.options.scopeParam];
  if (targetId !== actor.organizationUserId) {
    throw new ForbiddenException('Permission scope denied');
  }
}
```

***

## Messages d'Erreur Courants

| Erreur                                                  | Statut | Signification                                             | Solution                                              |
| ------------------------------------------------------- | ------ | --------------------------------------------------------- | ----------------------------------------------------- |
| "Authorization header is required"                      | 401    | Jeton d'accès manquant ou invalide                        | Connectez-vous et incluez un Bearer token valide      |
| "X-Organization-ID header is required"                  | 401    | En-tête organisation manquant                             | Inclure l'en-tête x-organization-id                   |
| "OrganizationUser not found for this organization"      | 401    | Utilisateur non membre de l'organisation                  | Vérifier l'ID organisation, vérifier l'appartenance   |
| "Insufficient permissions"                              | 403    | Autorisation requise totalement absente                   | Demander à l'administrateur d'accorder l'autorisation |
| "Insufficient permission scope"                         | 403    | Autorisation avec SELF, mais ANY requis                   | Demander à l'administrateur d'accorder la portée ANY  |
| "Permission scope denied"                               | 403    | Tentative d'accéder aux données d'autrui avec portée SELF | Accéder seulement à vos données, ou demander ANY      |
| "Protected role definitions cannot be deleted"          | 403    | Tentative de supprimer un rôle protégé                    | Impossible à supprimer, utiliser un autre rôle        |
| "Role definition is not editable"                       | 403    | Tentative de modifier un rôle non éditable                | Impossible à modifier, créer un nouveau rôle          |
| "Direct admin assignment is not allowed. Use set-admin" | 403    | Tentative d'assigner/retirer le rôle admin                | Utiliser l'endpoint set-admin                         |

***

## Exemples de Configurations de Rôles

Ces exemples sont indicatifs. Les rôles réels sont définis par l'organisation.

### Rôle Administrateur

**Autorisations suggérées** (toutes avec portée ANY) :

* `organization_users:write` - Gérer les membres
* `organization_user_roles:assign` - Assigner les rôles
* `savings:write` - Enregistrer des dépôts
* `loans:write`, `loans:modify`, `loans:approve` - Gestion complète des prêts
* `expenses:write` - Enregistrer des dépenses
* `assets:write` - Gérer les actifs
* `reserves:write` - Gérer les réserves
* `dividends:write` - Distribuer les dividendes
* `bank_accounts:write` - Gérer les comptes bancaires
* `ledger:write` - Publier des écritures comptables
* `settings:write` - Modifier les paramètres
* `periods:close` - Clôturer les périodes
* `audit_logs:read` - Voir les journaux d'activité
* `reports:read` - Accéder aux rapports

**Peut faire** : Tout

***

### Rôle Trésorier

**Autorisations suggérées** (toutes avec portée ANY) :

* `organization_users:read` - Voir les membres
* `savings:write` - Enregistrer dépôts/retraits
* `expenses:write` - Enregistrer des dépenses
* `bank_accounts:read` - Voir les comptes bancaires
* `ledger:read` - Voir le grand livre
* `reports:read` - Voir les rapports

**Peut faire** : Gérer les dépôts, enregistrer les dépenses, voir les rapports financiers

**Ne peut pas faire** : Créer des prêts, modifier les paramètres, assigner des rôles, clôturer des périodes

***

### Rôle Agent de Crédit

**Autorisations suggérées** (toutes avec portée ANY) :

* `organization_users:read` - Voir les membres
* `loans:write` - Créer et gérer les prêts
* `loans:modify` - Modifier les conditions de prêt
* `loans:approve` - Approuver les prêts
* `savings:read` - Voir l'épargne (vérifier l'éligibilité)
* `reports:read` - Voir les rapports

**Peut faire** : Gérer toutes les opérations de prêt

**Ne peut pas faire** : Enregistrer dépôts/dépenses, modifier les paramètres, assigner des rôles

***

### Rôle Comptable

**Autorisations suggérées** (toutes avec portée ANY) :

* `savings:read` - Voir l'historique des dépôts
* `loans:read` - Voir le portefeuille de prêts
* `expenses:read` - Voir les dépenses
* `assets:read` - Voir le registre des actifs
* `reserves:read` - Voir les soldes de réserves
* `dividends:read` - Voir l'historique des dividendes
* `bank_accounts:read` - Voir les comptes bancaires
* `ledger:read` - Accès complet au grand livre
* `ledger:write` - Publier des ajustements
* `reports:read` - Accéder aux rapports

**Peut faire** : Voir toutes les données financières, produire les rapports, publier des écritures comptables

**Ne peut pas faire** : Enregistrer des transactions opérationnelles (dépôts, prêts), assigner des rôles

***

### Rôle Membre

**Autorisations suggérées** (toutes avec portée SELF) :

* `organization_users:read` - Voir son propre profil
* `savings:read` - Voir son propre solde d'épargne
* `loans:read` - Voir ses propres prêts
* `ledger:read` - Voir son propre relevé de compte du grand livre

**Peut faire** : Voir ses propres informations financières

**Ne peut pas faire** : Voir les données des autres membres, enregistrer des transactions, accéder aux paramètres

**Spécial** : Assigner le rôle "member" crée automatiquement un compte d'épargne du grand livre

***

## Bonnes Pratiques

<Note>
  **Directives de gestion des autorisations :**

  **Principe du moindre privilège :**

  * ✅ Accorder uniquement les autorisations nécessaires à la fonction
  * ✅ Commencer avec des autorisations minimales, ajouter selon le besoin
  * ✅ Utiliser la portée SELF pour les rôles destinés aux membres
  * ✅ Réserver la portée ANY au personnel avec responsabilités globales

  **Conception des rôles :**

  * ✅ Créer des rôles correspondant aux vraies fonctions
  * ✅ Utiliser des noms de rôles descriptifs ("Trésorier", pas "Rôle1")
  * ✅ Documenter l'objectif du rôle dans le champ description
  * ✅ Utiliser des étiquettes couleur pour l'organisation visuelle
  * ✅ Limiter le nombre de rôles (5-10 typiquement)

  **Assignation des rôles :**

  * ✅ Assigner les rôles selon les responsabilités de l'utilisateur
  * ✅ Les utilisateurs peuvent avoir plusieurs rôles (autorisations cumulatives)
  * ✅ Antidater les assignations si nécessaire (champ assignedAt)
  * ✅ Examiner les assignations chaque trimestre
  * ✅ Révoquer rapidement les rôles lorsque les responsabilités changent

  **Sécurité :**

  * ✅ Protéger les rôles critiques (isProtected: true)
  * ✅ Limiter qui a `organization_user_roles:assign`
  * ✅ Auditer régulièrement les changements de rôles (voir journaux d'audit)
  * ✅ Ne pas créer de rôles "super utilisateur" trop permissifs
  * ✅ Séparer les responsabilités (comptable ≠ trésorier)

  **Utilisation des portées :**

  * ✅ Par défaut, utiliser SELF pour les rôles de membres
  * ✅ Utiliser ANY pour le personnel opérationnel (trésoriers, agents de crédit)
  * ✅ Se rappeler que ANY prend le dessus lorsqu'il est combiné
  * ✅ Tester les autorisations après assignation (vérifier l'accès)

  **Maintenance :**

  * ✅ Documenter la structure des rôles dans les politiques de l'organisation
  * ✅ Garder une trace écrite de qui a quels rôles et pourquoi
  * ✅ Revoir les définitions de rôles annuellement (retirer les rôles inutilisés)
  * ✅ Mettre à jour les grants lorsque de nouvelles fonctionnalités sont ajoutées
  * ✅ Former les utilisateurs à leurs autorisations et limites
</Note>

***

## Dépannage

**Q : Je ne vois pas le menu ou le bouton attendu dans l'interface**

R : Vous n'avez pas l'autorisation requise.

**Solution** :

1. Identifiez ce que vous essayez de faire
2. Vérifiez l'autorisation requise (voir la liste ci-dessus)
3. Demandez à l'administrateur d'accorder le rôle approprié
4. Déconnectez-vous puis reconnectez-vous (rafraîchit les autorisations)
5. Vérifiez que le menu/bouton est maintenant visible

***

**Q : Erreur : "Insufficient permissions"**

R : Vous n'avez pas du tout l'autorisation requise.

**Vérifier** :

* GET /me/permissions pour voir vos grants actuels
* Identifier l'autorisation manquante
* Demander à l'administrateur d'assigner un rôle avec cette autorisation

***

**Q : Erreur : "Insufficient permission scope"**

R : Vous avez l'autorisation avec portée SELF, mais l'endpoint exige la portée ANY.

**Exemple** : Voir les journaux d'audit exige `audit_logs:read` avec portée ANY.

**Solution** : Demandez à l'administrateur d'accorder l'autorisation avec portée ANY.

***

**Q : Erreur : "Permission scope denied"**

R : Vous avez l'autorisation avec portée SELF, mais vous essayez d'accéder aux données de quelqu'un d'autre.

**Exemple** : Vous avez `savings:read` avec portée SELF, mais vous avez essayé de voir l'épargne d'un autre membre.

**Solutions** :

* Accédez uniquement à vos propres données, OU
* Demandez à l'administrateur d'accorder la portée ANY

***

**Q : Je peux voir les données mais pas les modifier**

R : Vous avez l'autorisation `read` mais pas l'autorisation `write`.

**Exemple** : Vous pouvez voir les prêts (`loans:read`) mais pas les créer (besoin de `loans:write`).

**Solution** : Demandez l'autorisation `write` pour cette ressource.

***

**Q : L'administrateur a changé mon rôle mais je ne peux toujours pas accéder à la fonctionnalité**

R : Les autorisations sont mises en cache dans le jeton d'accès.

**Essayez** :

1. **Déconnectez-vous complètement**
2. **Reconnectez-vous** (rafraîchit le jeton avec les nouvelles autorisations)
3. **Réessayez l'action**

Si cela ne fonctionne toujours pas : le rôle peut ne pas inclure l'autorisation attendue. Demandez à l'administrateur de vérifier les grants du rôle.

***

**Q : Comment voir mes propres autorisations ?**

R : Appelez l'endpoint GET /me/permissions :

```bash theme={null}
curl -X GET "/me/permissions" \
  -H "Authorization: Bearer {token}" \
  -H "x-organization-id: {organizationId}"
```

La réponse montre toutes vos autorisations et portées.

***

**Q : Puis-je m'assigner des autorisations ?**

R : Seulement si vous avez l'autorisation `organization_user_roles:assign`. Vous ne pouvez pas dépasser vos propres autorisations.

**Sécurité** : Le système n'empêche pas l'auto-assignation. Les organisations doivent limiter qui a l'autorisation assign.

***

**Q : Que se passe-t-il lorsqu'un utilisateur a plusieurs rôles ?**

R : Les autorisations sont **cumulatives** (union de tous les rôles).

**Exemple** :

* Rôle A accorde : `savings:read` (SELF), `loans:read` (SELF)
* Rôle B accorde : `savings:read` (ANY), `expenses:write` (ANY)
* **Grants effectifs** : `savings:read` (ANY), `loans:read` (SELF), `expenses:write` (ANY)

**Remarque** : La portée ANY prend le dessus lorsque la même autorisation est accordée avec différentes portées.

***

**Q : Comment créer un rôle personnalisé ?**

R : Utilisez les endpoints API de gestion des rôles :

1. POST /role-definitions (créer le rôle)
2. PUT /role-definitions/{id}/grants (ajouter les autorisations)
3. POST /organization-users/{userId}/role-assignments (assigner aux utilisateurs)

Voir la documentation des endpoints API ci-dessus pour les détails.

***

## Sujets Connexes

<CardGroup cols={2}>
  <Card title="Rôles des Membres" icon="users" href="/fr/tontines/organization-users/roles">
    Guide de gestion des rôles
  </Card>

  <Card title="Matrice des Autorisations" icon="table" href="/fr/tontines/reference/permissions-matrix">
    Référence complète des autorisations
  </Card>

  <Card title="Gestion des Membres" icon="user-plus" href="/fr/tontines/organization-users/managing-users">
    Ajouter et gérer les utilisateurs de l'organisation
  </Card>

  <Card title="Piste d'Audit" icon="file-magnifying-glass" href="/fr/tontines/advanced/audit-trail">
    Suivre les changements de rôles et d'autorisations
  </Card>
</CardGroup>