Gérer les membres

Un espace de travail Coffrify regroupe les personnes qui collaborent sur vos transferts, vos réceptions et vos coffres. L'API vous donne une vue programmatique de cet annuaire : vous pouvez récupérer la liste complète des membres, connaître leur rôle et leur statut, et bâtir vos propres tableaux de bord ou synchronisations. Cette page décrit la lecture des membres avec GET /v1/members, la structure d'un objet membre, et la relation entre le rôle d'une personne et les scopes des clés API qui pilotent l'accès programmatique.

Lister les membres

L'endpoint GET /v1/members renvoie l'ensemble des membres de l'espace de travail associé à votre clé API. Il requiert le scope members:read. Si votre clé ne possède pas ce scope, l'API répond avec une erreur scope_missing.

La réponse est une liste paginée par curseur. Vous contrôlez la taille de page avec limit (100 au maximum) et vous parcourez les pages suivantes en passant next_cursor dans le paramètre cursor. Chaque réponse indique has_more pour savoir s'il reste des résultats.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const members = await coffrify.members.list({ limit: 50 });
 
for (const member of members.data) {
  console.log(member.email, member.role, member.status);
}

Exemple de réponse renvoyée par l'API :

{
  "object": "list",
  "data": [
    {
      "id": "mem_3f9k2p",
      "email": "dupont@exemple.fr",
      "role": "admin",
      "status": "active"
    },
    {
      "id": "mem_7h1m4q",
      "email": "martin@exemple.fr",
      "role": "member",
      "status": "invited"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Structure d'un membre

Chaque membre est représenté par un objet aux champs stables. Vous pouvez vous appuyer sur l'id comme identifiant durable, par exemple pour modifier un rôle ou retirer une personne via les endpoints PATCH /v1/members/{id} et DELETE /v1/members/{id}.

Rôles des membres et scopes des clés

Il faut distinguer deux mécanismes d'accès. Le rôle d'un membre régit ce qu'une personne peut faire dans l'interface de l'espace de travail. Les scopes d'une clé API régissent ce qu'une intégration peut faire via l'API. Les deux sont indépendants : une clé n'agit que dans la limite de ses scopes, quel que soit le rôle de la personne qui l'a créée.

Concrètement, pour qu'un programme puisse gérer l'équipe, sa clé API doit porter les scopes adéquats. La lecture des membres demande members:read ; l'envoi d'invitations demande members:invite ; la modification d'un rôle ou le retrait d'un membre demandent members:manage. Vous attribuez ces scopes au moment de la création de la clé.

Suivre les changements via webhooks

Pour réagir aux évolutions de l'équipe sans interroger l'API en boucle, abonnez-vous aux évènements webhook. Coffrify émet notamment member.invited, member.accepted, member.removed et member.role_changed, ainsi que invitation.expired et invitation.revoked pour le cycle de vie des invitations.

• member.invited : une invitation vient d'être envoyée.
• member.accepted : la personne a accepté et passe au statut active.
• member.role_changed : le rôle d'un membre a été modifié.
• member.removed : un membre a été retiré de l'espace de travail.