> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.goodflag.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.goodflag.com/_mcp/server.

# Groupes, rôles et droits

> Modèle de droits porté par les groupes, rôles basiques / administration / développement, autorisations inter-groupes

# Groupes, rôles & droits

## Principe : les droits vivent dans le groupe

Dans un tenant, **les droits d'un utilisateur sont ceux de son groupe**. Un utilisateur
appartient à **un et un seul groupe** (champ `groupId` de l'utilisateur, obligatoire) et
hérite des **rôles** qui y sont attachés. Un groupe peut, lui, compter autant
d'utilisateurs que nécessaire — ou un seul, lorsqu'on veut des droits « individuels ».

Le tenant désigne par ailleurs un **groupe par défaut** (`defaultGroupId` ; ce groupe
porte alors `isDefault: true`), auquel un utilisateur est rattaché automatiquement lors de
certains provisionnements (Azure, Google, Keycloak, etc.).

Un groupe définit :

* des **rôles** (`userRoles`) — ce que ses membres ont le droit de faire (section [*Les rôles (userRoles)*](#les-roles-userroles)) ;
* des **autorisations inter-groupes** — agir sur les utilisateurs et les parapheurs
  d'autres groupes (section [*Autorisations inter-groupes*](#autorisations-inter-groupes)) ;
* un **cadrage** de l'usage des modèles, des dispositions de métadonnées et de la visibilité des
  destinataires (section [*Cadrage de l'usage*](#cadrage-de-lusage)) ;
* une politique d'**invitations groupées** (section [*Invitations groupées (groupedInvitations)*](#invitations-groupees-groupedinvitations)).

> À la mise en place de votre tenant, l'éventail des groupes et des droits disponibles est
> défini par Goodflag. Vous administrez ensuite librement vos groupes dans ce cadre.

L'intérêt principal des groupes est d'isoler des groupes d'utilisateurs les uns par rapport aux autres. Ainsi par exemple il peut être intéressant pour les utilisateurs clients de l'entreprise de faire partie d'un groupe "Clients" et ainsi de disposer de la possibilité de se connecter au portail avec leur propre compte leur permettant de visualiser leurs propres parapheurs uniquement. Dans un autre cas, il peut être souhaitable pour les membres d'un groupe d'utilisateurs "RH" appartenant au département des ressources humaines de visualiser tous les parapheurs de tous les membres du groupe.

## Créer & configurer un groupe

```http
POST /api/tenants/{tenantId}/groups
Authorization: Bearer act_<id>.<secret>
Content-Type: application/json

{
  "name": "Back-office signatures",
  "description": "Équipe qui pilote les parapheurs",
  "userRoles": [ "portalUser", "workflowCreator", "workflowManager", "developer" ],
  "templateSelectionMode": "any",
  "layoutSelectionMode": "listOrNull",
  "allowedLayouts": [ "lay_…" ],
  "hideWorkflowRecipients": false
}
```

| Champ                                        | Type                          | Rôle                                                                                                                        |
| -------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`                                       | String                        | Nom du groupe.                                                                                                              |
| `description`                                | String *(facultatif)*         | Description libre.                                                                                                          |
| `isDisabled`                                 | Boolean *(facultatif)*        | Groupe désactivé ou non.                                                                                                    |
| `userRoles`                                  | Array *(facultatif)*          | Les **rôles** accordés aux membres (section [*Les rôles (userRoles)*](#les-roles-userroles)).                               |
| `hideWorkflowRecipients`                     | Boolean *(facultatif)*        | Masquer aux membres les autres destinataires d'un parapheur.                                                                |
| `templateSelectionMode` / `allowedTemplates` | String / Array *(facultatif)* | Cadrage des **modèles** (section [*Cadrage de l'usage*](#cadrage-de-lusage)).                                               |
| `layoutSelectionMode` / `allowedLayouts`     | String / Array *(facultatif)* | Cadrage des **dispositions de métadonnées** (section [*Cadrage de l'usage*](#cadrage-de-lusage)).                           |
| `…AuthorizedGroups`                          | Array *(facultatif)*          | **Autorisations inter-groupes** (section [*Autorisations inter-groupes*](#autorisations-inter-groupes)).                    |
| `groupedInvitations`                         | Object *(facultatif)*         | **Invitations groupées** (section [*Invitations groupées (groupedInvitations)*](#invitations-groupees-groupedinvitations)). |

La réponse renvoie le groupe créé (`id` préfixé `grp_`, `isDefault`, dates, `ETag`…).

## Les rôles (`userRoles`)

Les rôles se répartissent en trois familles. Le champ `userRoles` attend la liste des
**identifiants** ci-dessous.

### Rôles basiques

| Identifiant                  | Permet à ses membres de…                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `portalUser`                 | accéder au Portail et créer leurs propres favoris ;                                   |
| `workflowCreator`            | créer leurs propres parapheurs ;                                                      |
| `contactCreator`             | créer leurs propres contacts ;                                                        |
| `signer`                     | signer des parapheurs ;                                                               |
| `approver`                   | valider des parapheurs ;                                                              |
| `userViewer`                 | visualiser tous les utilisateurs du tenant ;                                          |
| `workflowViewer`             | visualiser tous les parapheurs du tenant ;                                            |
| `workflowEvidenceDownloader` | télécharger les dossiers de preuve de leurs propres parapheurs ;                      |
| `workflowDeleter`            | supprimer leurs propres parapheurs ;                                                  |
| `workflowArchiver`           | clôturer leurs propres parapheurs ;                                                   |
| `workflowCoManager`          | permet d'être désigné comme visualiseur et cogestionnaire de parapheurs ;             |
| `selfAnonymizer`             | anonymiser leur propre compte ;                                                       |
| `exportViewer`               | rechercher et visualiser tous les exports du tenant ;                                 |
| `bulkViewer`                 | exporter en masse les documents et pièces jointes de ses propres parapheurs terminés. |

### Rôles d'administration

| Identifiant           | Administre…                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `tenantManager`       | la **configuration du tenant** (et, à ce titre, pages de consentement, profils de signature, webhooks, exports, journaux, preuves) ; |
| `groupManager`        | tous les **groupes** ;                                                                                                               |
| `userManager`         | tous les **utilisateurs** (création, gestion, anonymisation) ;                                                                       |
| `consentPageManager`  | toutes les **pages de consentement** ;                                                                                               |
| `organizationManager` | toutes les **organisations** ;                                                                                                       |
| `templateManager`     | tous les **modèles** ;                                                                                                               |
| `layoutManager`       | toutes les **dispositions de métadonnées** (« Administrateur des dispositions de métadonnées ») ;                                    |
| `workflowManager`     | tous les **parapheurs** du tenant.                                                                                                   |

### Rôles de développement

| Identifiant       | Permet de…                                                                                                                                                                       |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `developer`       | créer ses **jetons d'API** et ses **webhooks** — **c'est le rôle indispensable pour intégrer l'API** (voir fondation [*Authentification*](/wm/api-reference/authentification)) ; |
| `workflowInviter` | créer des **invitations** pour tous les parapheurs du tenant.                                                                                                                    |

## Autorisations inter-groupes

Par défaut, un rôle porte sur les objets **propres** à l'utilisateur ou à son groupe. Pour
déléguer à un groupe le droit d'agir sur les **utilisateurs** ou les **parapheurs d'autres
groupes**, on renseigne huit listes d'identifiants de groupes :

| Sur les **utilisateurs**     | Sur les **parapheurs**           | Action                                                     |
| ---------------------------- | -------------------------------- | ---------------------------------------------------------- |
| `viewUserAuthorizedGroups`   | `viewWorkflowAuthorizedGroups`   | **Voir** (consulter, rechercher, exporter)                 |
| `createUserAuthorizedGroups` | `createWorkflowAuthorizedGroups` | **Créer / transférer**                                     |
| `updateUserAuthorizedGroups` | `updateWorkflowAuthorizedGroups` | **Gérer** (modifier)                                       |
| `deleteUserAuthorizedGroups` | `deleteWorkflowAuthorizedGroups` | **Anonymiser** (utilisateurs) / **Supprimer** (parapheurs) |

Chaque liste contient les **identifiants des groupes** dont les membres reçoivent
l'autorisation. L'alias **`self`** désigne le groupe courant. Exemple : un groupe
« Back-office » qui gère les utilisateurs et parapheurs des groupes métier.

## Cadrage de l'usage

* **Modèles** — `templateSelectionMode` gouverne l'emploi des modèles par les créateurs de
  parapheurs du groupe :

| Valeur       | Signification                               |
| ------------ | ------------------------------------------- |
| `any`        | libre                                       |
| `anyOrNull`  | libre ou aucun                              |
| `list`       | choisir parmi la liste (`allowedTemplates`) |
| `listOrNull` | choisir parmi la liste, ou aucun            |

* **Dispositions de métadonnées** — `layoutSelectionMode` fonctionne à l'identique, avec `allowedLayouts`.
* **Destinataires** — `hideWorkflowRecipients` masque aux membres les autres destinataires
  d'un parapheur.

## Invitations groupées (`groupedInvitations`)

Permet de regrouper les notifications envoyées aux membres du groupe plutôt que de les
envoyer une par une :

* `mode` — activation du regroupement ;
* `activeDays` — jours de la semaine d'envoi ;
* `sendingSlots` — créneaux d'envoi, chacun avec `time` (format `HH:mm`) et `zone`
  (ex. `Europe/Paris`).

## Cycle de vie d'un groupe

* **Consulter** — `GET /api/groups/{id}`.
* **Modifier** — `PATCH /api/groups/{id}` (concurrence optimiste `If-Match`, fondation [*Structure > Concurrence : l'en-tête conditionnel `If-Match`*](/wm/api-reference/structure#concurrence-len-tete-conditionnel-if-match)).
* **Supprimer** — `DELETE /api/groups/{id}`.
* **Lister / rechercher** — `GET /api/groups` (filtres et pagination, fondation [*Structure > Recherche & pagination*](/wm/api-reference/structure#recherche-pagination)).