Cette page s’adresse aux administrateurs qui souhaitent gérer les membres d’une organisation depuis un programme. Elle explique ce qu’une clé API ne peut pas faire avec les membres, comment un fournisseur d’identité crée et supprime des membres via SCIM 2.0, et quels webhooks signalent les modifications de membres.
Ce qu’une clé API ne peut pas faire
Les membres, invitations, rôles et groupes ne sont gérés que dans l’application. Aucune clé API ne peut appeler ces routes, quelles que soient les permissions que vous tentez de lui accorder :
| Tâche | Où le faire |
|---|---|
| Lister les membres, consulter un membre, voir son activité | Page Membres |
| Inviter des personnes, renvoyer, relancer ou révoquer une invitation | Page Membres (Invite Member) |
| Modifier le rôle ou les groupes d’un membre, suspendre, supprimer | La page du membre |
| Modifier les rôles, les groupes et la matrice des permissions | Paramètres > Access Control |
| Transférer la propriété | Dans l’application (propriétaire uniquement) |
| Créer, mettre à jour et désactiver des membres depuis votre fournisseur d’identité | SCIM 2.0 (ci-dessous) |
C’est délibéré. Une clé ne peut jamais détenir les permissions des parties identité et accès de Hermetry : membres, invitations, paramètres de l’organisation, clés API, sessions et connexion. Une clé divulguée ne doit pas pouvoir ajouter une personne, élever un rôle ou inviter une adresse extérieure. Une clé qui appelle une route de membre ou d’invitation obtient :
{ "message": "API key does not have the required permission.", "code": "FORBIDDEN" }
avec le statut 403. L’acceptation ou le refus d’une invitation se fait par la personne invitée, connectée ; les clés ne fonctionnent jamais sur les routes de compte. Voir Authentification pour la règle complète.
Provisionner des membres avec SCIM 2.0
SCIM permet à votre fournisseur d’identité de créer, mettre à jour et désactiver des membres. La configuration dans l’application (le point d’accès et le jeton SCIM) se trouve sur Authentification unique (SAML) et provisionnement. Cette section est la référence des routes pour une intégration qui appelle SCIM elle-même.
Tous les chemins SCIM se trouvent sous https://<your host>/tenant/<tenantId>/api/scim/v2. Envoyez le jeton SCIM dans Authorization: Bearer <token>. Les lectures nécessitent le scope scim:read, les écritures le scope scim:write. Le jeton doit appartenir à l’organisation indiquée dans le chemin.
| Méthode | Chemin | Scope | Action |
|---|---|---|---|
| GET | /Users | scim:read | Lister les membres |
| POST | /Users | scim:write | Créer un membre ; 201 avec Location et ETag |
| GET | /Users/{id} | scim:read | Un membre, avec son ETag |
| PUT | /Users/{id} | scim:write | Remplacer un membre |
| PATCH | /Users/{id} | scim:write | Modifier certains attributs |
| DELETE | /Users/{id} | scim:write | Désprovisionner ; 204 |
| GET, POST | /Groups | lecture / écriture | Lister ou créer des groupes |
| GET, PUT, PATCH, DELETE | /Groups/{id} | lecture / écriture | Un groupe |
| GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | aucun | Découverte pour les fournisseurs d’identité |
Les réponses et erreurs utilisent Content-Type: application/scim+json.
Correspondance des attributs
| Attribut SCIM | Dans Hermetry |
|---|---|
id | L’identifiant du membre dans cette organisation |
userName, valeur emails principale | L’e-mail du compte |
externalId | L’identifiant externe SCIM sur la page du membre (256 caractères maximum) |
active | Statut du membre : true Actif, false Inactif |
name, displayName | Enregistrés lorsque Keep names in step est activé (par défaut) et que le compte n’appartient qu’à votre organisation |
Un nouveau membre reçoit le rôle SCIM par défaut (User, sauf si vous le modifiez dans les paramètres SCIM). Les rôles issus des groupes sont définis dans Groups and roles.
Listes
GET /Users lit startIndex (à partir de 1), count (100 par défaut, 200 au maximum), sortBy et sortOrder (ascending ou descending). Les seuls filtres sont l’égalité sur userName ou externalId :
GET /Users?filter=userName eq "ana@example.com"
GET /Users?filter=externalId eq "00u1a2b3c4"
Tout autre filtre répond 400 avec scimType invalidFilter.
Règles de création
- Une nouvelle adresse e-mail crée le compte et le membre.
- Un compte existant qui n’est pas membre de votre organisation est refusé avec
409(uniqueness) : « Un compte avec ce userName existe déjà et n’est pas membre de cette organisation. Il rejoint par invitation. » Invitez d’abord la personne dans l’application ; ensuite, SCIM gère l’appartenance.
Modifications faites par quelqu’un d’autre
GET /Users/{id} renvoie un ETag. Envoyez-le dans If-Match sur PUT, PATCH ou DELETE ; si le membre a changé entre-temps, la réponse est 412. If-None-Match sur un GET répond 304 lorsque rien n’a changé.
Groupes
Les routes de groupes répondent 501 (« Les groupes SCIM ne sont pas activés pour ce tenant. ») tant que les groupes ne sont pas activés dans les paramètres SCIM. Lorsque les groupes sont activés, le rôle d’un membre suit les groupes associés à des rôles. Le dernier propriétaire actif n’est jamais rétrogradé par une modification de groupe.
Exemple
curl 'https://<your-host>/tenant/{tenantId}/api/scim/v2/Users?filter=userName%20eq%20%22ana@example.com%22' \
-H 'Authorization: Bearer sk_live_…'
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [ { "id": "4b2e…", "userName": "ana@example.com", "active": true, "…": "…" } ]
}
Erreurs SCIM
| Statut | scimType | Quand |
|---|---|---|
| 400 | invalidFilter | Un filtre autre que userName eq ou externalId eq |
| 400 | invalidSyntax, invalidValue | Un corps qui n’est pas du JSON ou qui ne respecte pas le schéma |
| 401 | aucun | « Jeton bearer invalide. » : le jeton est inconnu, expiré, d’une autre organisation ou n’a pas le scope |
| 404 | aucun | Aucun membre avec cet identifiant dans votre organisation |
| 409 | uniqueness | L’e-mail est déjà pris, ou le compte existe et n’est pas membre |
| 412 | aucun | If-Match ne correspond pas à l’ETag actuel du membre |
| 429 | aucun | « Trop de requêtes. Veuillez ralentir. » |
| 501 | aucun | Les groupes ne sont pas activés |
Suivre les modifications de membres avec des webhooks
Pour tenir un autre système à jour sans interrogation, abonnez un webhook à ces événements (voir Webhooks) :
| Événement | Envoyé lorsque |
|---|---|
member.created, member.updated, member.deleted | Un membre est ajouté, modifié ou supprimé |
invitation.sent, invitation.accepted, invitation.declined, invitation.revoked | Une invitation change d’état |
scim.user.provisioned, scim.user.updated, scim.user.deprovisioned | Votre fournisseur d’identité a modifié un membre via SCIM |

