Inviter des membres

Inviter des membres dans votre espace de travail Coffrify se fait en un seul appel à l'API REST v1. Vous fournissez une adresse e-mail et un rôle, et Coffrify envoie l'invitation, crée une entrée en attente et déclenche les évènements correspondants. Cette page décrit comment créer une invitation, lister celles qui sont en cours, en révoquer une, et suivre le cycle de vie complet depuis l'envoi jusqu'à l'acceptation. Toutes les requêtes s'authentifient avec une clé API portée par l'en-tête Authorization: Bearer <clé> et sont soumises aux scopes décrits ci-dessous.

Inviter un membre

Pour inviter une personne, envoyez une requête à POST /v1/members/invitations avec l'adresse e-mail du destinataire et le rôle que vous souhaitez lui attribuer. Coffrify envoie l'invitation par e-mail et renvoie l'objet d'invitation créé, dont l'identifiant et le statut. Comme il s'agit d'une écriture, ajoutez un en-tête Idempotency-Key (entre 8 et 255 caractères) pour pouvoir rejouer la requête sans risque de doublon.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const invitation = await coffrify.members.invitations.create(
  {
    email: 'nouvelle.recrue@exemple.fr',
    role: 'member',
  },
  { idempotencyKey: 'invite-nouvelle-recrue-2026-06' }
);
 
console.log(invitation.id, invitation.status);

La réponse contient l'objet d'invitation. Le champ status vaut pending tant que la personne n'a pas accepté. Conservez le champ id : il vous servira à révoquer l'invitation si besoin.

{
  "object": "invitation",
  "id": "inv_8sKd2mWq",
  "email": "nouvelle.recrue@exemple.fr",
  "role": "member",
  "status": "pending",
  "created_at": "2026-06-10T09:14:00Z",
  "expires_at": "2026-06-17T09:14:00Z"
}

Lister les invitations en attente

Pour voir les invitations en cours, appelez GET /v1/members/invitations. La réponse est une liste paginée par curseur : utilisez limit (100 au maximum) et cursor, puis suivez next_cursor tant que has_more vaut true.

const { data, has_more, next_cursor } =
  await coffrify.members.invitations.list({ limit: 50 });
 
for (const invitation of data) {
  console.log(invitation.email, invitation.status);
}

Pour obtenir la liste des personnes ayant déjà rejoint l'espace de travail, utilisez GET /v1/members (scope members:read). Une invitation acceptée disparaît de la liste des invitations et apparaît parmi les membres.

Révoquer une invitation

Une invitation envoyée par erreur, ou qui n'a plus lieu d'être, se révoque en supprimant l'invitation par son identifiant. La personne ne pourra plus l'accepter, et un évènement invitation.revoked est émis.

$ curl -X DELETE https://api.coffrify.com/v1/members/invitations/inv_8sKd2mWq \
  -H "Authorization: Bearer $COFFRIFY_API_KEY"

Cycle de vie d'une invitation

Chaque étape de l'invitation déclenche un évènement webhook. Abonnez-vous à ces évènements pour synchroniser votre propre système, par exemple pour mettre à jour un annuaire interne ou alerter un administrateur lorsqu'une personne rejoint l'équipe.

D'autres évènements concernent la suite de la vie d'un membre : member.role_changed lorsqu'un rôle est modifié via PATCH /v1/members/{id}, et member.removed lorsqu'un membre est retiré via DELETE /v1/members/{id}. Les espaces de travail Entreprise disposent en plus d'évènements liés au SSO/SAML (saml.login_succeeded, saml.login_failed) et au provisionnement SCIM (scim.user_provisioned, scim.user_deprovisioned).

Gestion des erreurs

Les erreurs suivent toujours la même forme {"error":{"code","message","request_id"}}. Lors de l'invitation de membres, vous rencontrerez principalement validation_error (e-mail ou rôle invalide), scope_missing (la clé n'a pas le droit members:invite ou members:manage), invalid_api_key (clé absente ou incorrecte) et not_found (identifiant d'invitation inconnu lors d'une révocation). En cas de dépassement du débit autorisé, l'API renvoie rate_limited avec un code 429 et un en-tête Retry-After indiquant le délai avant de réessayer.