Rôles et permissions

Comprendre les rôles d'un membre, les changer ou retirer un membre via l'API, et appliquer le moindre privilège aux clés API grâce aux scopes.

Dans un workspace Coffrify, deux mécanismes de contrôle d'accès coexistent et ne doivent pas être confondus. D'un côté, le rôle décrit ce qu'une personne (un membre humain) peut faire dans l'interface et au sein du workspace. De l'autre, les scopes décrivent ce qu'une clé API est autorisée à faire au nom du workspace, indépendamment de la personne qui l'a créée. Cette page explique les rôles disponibles, comment changer le rôle d'un membre via PATCH /v1/members/{id}, comment retirer un membre via DELETE, comment les rôles s'articulent avec les scopes, et comment appliquer le principe de moindre privilège.

Les rôles disponibles

Chaque membre d'un workspace porte exactement un rôle. Le rôle owner est particulier : c'est le propriétaire du workspace, et il ne peut être ni rétrogradé ni retiré par l'API (voir plus bas). Les autres rôles peuvent être attribués librement à un membre existant.

Rôle	Vocation
owner	Propriétaire du workspace. Contrôle total. Protégé : non modifiable et non supprimable par l'API.
admin	Administration courante : membres, paramètres, facturation, sécurité.
developer	Profil technique : transferts, clés API, webhooks, intégrations.
member	Membre standard : envoie et gère ses transferts au quotidien.
read_only	Lecture seule sur les ressources du workspace.
auditor	Profil conformité : consultation de l'audit et des journaux.
viewer	Consultation restreinte, sans action d'écriture.

Changer le rôle d'un membre

Pour faire évoluer un membre (par exemple promouvoir un member en admin, ou basculer quelqu'un en auditor), envoyez un PATCH sur le membre avec le nouveau rôle. L'identifiant attendu est celui du membre (id renvoyé par GET /v1/members), pas l'identifiant de l'utilisateur.

PATCH/v1/members/{id}Change le rôle d'un membre. Scope requis members:manage. Le corps contient { role }. Le rôle doit être l'un de admin, developer, member, read_only, auditor, viewer.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const updated = await coffrify.members.updateRole('mbr_8sJ2', 'admin');
 
console.log(updated.previous_role, '->', updated.role);
// 'member' -> 'admin'

La réponse confirme le membre, son nouveau rôle, et inclut previous_role pour que vous puissiez journaliser le changement de votre côté. Le champ status indique l'état du membre (active, pending ou suspended).

{
  "id": "mbr_8sJ2",
  "user_id": "usr_a1B2c3",
  "role": "admin",
  "status": "active",
  "previous_role": "member"
}

Retirer un membre

Pour retirer définitivement un membre du workspace, envoyez un DELETE sur ce membre. L'opération révoque son appartenance ; elle ne supprime pas son compte Coffrify, seulement son accès à ce workspace.

DELETE/v1/members/{id}Retire un membre du workspace. Scope requis members:manage. Le propriétaire (owner) ne peut pas être retiré.

const res = await coffrify.members.remove('mbr_8sJ2');
 
console.log(res.removed); // true

La réponse confirme le retrait. Comme pour le changement de rôle, tenter de retirer le propriétaire renvoie une 409 (« Cannot remove the workspace owner »).

{
  "id": "mbr_8sJ2",
  "object": "workspace_member",
  "removed": true
}

Rôles (humains) contre scopes (clés API)

Le rôle gouverne ce qu'une personne peut faire. Les scopes gouvernent ce qu'une clé API peut faire. Une clé n'hérite pas du rôle de la personne qui l'a émise : elle ne porte que les scopes qu'on lui a explicitement accordés à la création. Pour la gestion d'équipe, trois scopes entrent en jeu, du moins puissant au plus puissant.

Scope	Permet	Impact
members:read	Lister les membres et les invitations (GET).	Faible
members:invite	Créer et lister des invitations.	Moyen
members:manage	Inviter, changer un rôle (PATCH), retirer un membre (DELETE).	Contrôle du workspace

Ainsi, GET /v1/members exige members:read, tandis que PATCH et DELETE exigent members:manage. Une clé qui ne porterait que members:read recevra une erreur 403 scope_missing si elle tente un changement de rôle, avec un message listant les scopes effectivement accordés.

Réagir aux changements via webhooks

Plutôt que d'interroger l'API en boucle, abonnez-vous aux évènements de cycle de vie pour synchroniser votre annuaire interne en temps réel. Les changements de rôle et de composition d'équipe émettent les évènements suivants.

member.invited, member.accepted, member.removed : invitation, arrivée, départ d'un membre.
member.role_changed : un rôle a changé. La charge utile contient member_id, old_role et new_role.
invitation.expired, invitation.revoked : une invitation expire ou est annulée.

Bonnes pratiques de moindre privilège

Le moindre privilège consiste à n'accorder, à chaque rôle et à chaque clé, que ce qui est strictement nécessaire. Quelques principes concrets :

Réservez members:manage aux clés qui pilotent réellement l'équipe. Pour un tableau de bord en lecture, members:read suffit.
Préférez des clés restreintes (préfixe cof_rk_) avec une liste de scopes explicite, plutôt qu'une clé pleine qui détient tout.
Côté humains, attribuez read_only, viewer ou auditor par défaut, et ne montez en admin que les personnes qui administrent vraiment le workspace.
Émettez des clés distinctes par usage (intégration, script, CI) : une fuite reste ainsi cantonnée à un périmètre étroit, et la rotation est indolore.
Testez vos automatisations avec une clé cof_test_ ou une clé cof_sandbox_ (environnement isolé, expirant en 24 h) avant de basculer en cof_live_.

Enfin, toute opération sensible reste traçable : les changements de rôle et les retraits apparaissent dans le journal d'audit du workspace, consultable via GET /v1/audit. Combinez webhooks pour la réaction immédiate et audit pour la revue a posteriori afin de garder une vision complète de qui peut faire quoi, et depuis quand.