Aperçu
Passinstance repose sur un moteur hiérarchique de contrôle d'accès basé sur les rôles (RBAC) à moindre privilège (Team Permissions API sur /api/v1/rbac/*, administré visuellement dans le tableau de bord via Paramètres de l'espace -> Membres & rôles : /settings/workspace/members, /settings/workspace/roles et /settings/workspace/roles/permission-matrix) qui sépare la gouvernance au niveau Organisation (OrganizationMemberRole : OWNER | ADMIN | MEMBER) des rôles opérationnels d'espace de travail. Les administrateurs peuvent inviter des membres (POST /api/v1/users/invitations), créer des rôles personnalisés avec héritage, exiger l'authentification à deux facteurs (2FA) par rôle et limiter les opérateurs à certains modèles de cartes (template-access).
Architecture RBAC multiniveau & cloisonnement par modèle
Important : Les contrôles d'autorisation sont appliqués strictement côté serveur dans les couches contrôleur et service NestJS. Restreindre un rôle personnalisé via
template-accessgarantit que l'opérateur ne peut ni consulter, ni modifier, ni exporter des cartes appartenant à des modèles non autorisés, même en appelant directement l'API REST.
Rôles d'Organisation vs. rôles d'Espace de travail
Passinstance distingue l'appartenance globale à l'Organisation des autorisations propres à un Espace de travail (Customer) :
| Niveau & Rôle | Périmètre | Capacités & permissions principales |
|---|---|---|
Organization OWNER | Tous les espaces de l'organisation | Contrôle complet de la facturation consolidée (GET /api/v1/organizations/current/billing-summary), création/suppression d'espaces, configuration SSO SAML 2.0 et transfert de propriété. |
Organization ADMIN | Espaces affectés / tous | Gestion des invitations d'équipe, paramètres d'espace, certificats de signature Apple/Google, clés API (api:keys-manage) et webhooks. |
Workspace Editor (MEMBER) | Espace unique | Création et édition des modèles de cartes, configuration des mécaniques et paliers, exécution des imports CSV par lots et campagnes du centre de diffusion. |
Workspace Operator | Espace unique / Modèles autorisés | Émission ou recherche de cartes individuelles, utilisation des scanners web/mobiles et consultation des rapports de scan autorisés sans accès à la facturation ni aux clés API. |
Rôles personnalisés, héritage & portées de permissions (Team Permissions API)
Lorsque les rôles natifs sont trop larges pour certaines équipes (par exemple une agence marketing externe ou un responsable de point de vente régional), les administrateurs peuvent définir des rôles sur mesure dans Compte → Membres de l'équipe → Rôles & permissions.
Endpoints RBAC principaux
| Endpoint | Méthode HTTP | Description |
|---|---|---|
/api/v1/rbac/roles | GET | Liste tous les rôles système et personnalisés définis dans l'espace actif. |
/api/v1/rbac/roles | POST | Crée un rôle RBAC personnalisé avec jetons d'autorisation explicites et héritage optionnel d'un rôle parent. |
/api/v1/rbac/roles/:roleId | PUT | Met à jour le nom, la description, la règle requireTwoFactor ou les permissions d'un rôle personnalisé. |
/api/v1/rbac/roles/:roleId | DELETE | Supprime un rôle personnalisé (échoue proprement si des membres actifs y sont encore rattachés). |
/api/v1/rbac/roles/:roleId/inheritance | GET | Retourne le graphe d'héritage parent-enfant du rôle ciblé. |
/api/v1/rbac/roles/:roleId/inherited-permissions | GET | Calcule l'union effective des permissions directes et des permissions héritées des rôles parents. |
/api/v1/rbac/roles/:roleId/template-access | POST | Lie le rôle à une liste autorisée explicite de templateIds (accessMode: 'SCOPED'). |
Créer un rôle personnalisé avec héritage
POST /api/v1/rbac/roles HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Regional Event Coordinator",
"description": "Can manage passes and view scan analytics for assigned event templates only.",
"parentRoleId": "rol_builtin_operator",
"requireTwoFactor": true,
"permissions": [
"passes:read",
"passes:write",
"passes:export",
"scans:read",
"analytics:read"
]
}
Charge utile de réponse (201 Created)
{
"id": "rol_01933210-8b44-7c00-9e12-445566778899",
"name": "Regional Event Coordinator",
"description": "Can manage passes and view scan analytics for assigned event templates only.",
"isSystemRole": false,
"parentRoleId": "rol_builtin_operator",
"requireTwoFactor": true,
"permissions": [
"passes:read",
"passes:write",
"passes:export",
"scans:read",
"analytics:read"
],
"createdAt": "2026-11-15T23:34:30.000Z"
}
Restreindre un rôle à des modèles spécifiques (template-access)
Pour isoler un rôle personnalisé afin que ses membres ne puissent consulter et gérer que les cartes rattachées à certains modèles :
POST /api/v1/rbac/roles/rol_01933210-8b44-7c00-9e12-445566778899/template-access HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"accessMode": "SCOPED",
"templateIds": [
"b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"c8e12a90-41b2-4f00-8a11-998877665544"
],
"allowedActions": ["READ", "ISSUE_PASS", "SCAN_PASS", "EXPORT_DATA"]
}
{
"roleId": "rol_01933210-8b44-7c00-9e12-445566778899",
"accessMode": "SCOPED",
"scopedTemplateCount": 2,
"templateIds": [
"b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"c8e12a90-41b2-4f00-8a11-998877665544"
],
"updatedAt": "2026-11-15T23:35:02.000Z"
}
Documentation connexe
-
Gérez des structures multi-espaces d'agences dans Gestion multi-clients.
-
Configurez votre 2FA TOTP personnelle dans Profil & préférences.
-
Consultez l'export du journal d'audit dans Sécurité du compte & accès.
