Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

API Membres

Ce qu'un programme peut faire avec les membres d'une organisation : les provisionner via SCIM 2.0 et suivre les modifications avec des webhooks. Les clés API ne peuvent pas gérer les membres ni les invitations.

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âcheOù le faire
Lister les membres, consulter un membre, voir son activitéPage Membres
Inviter des personnes, renvoyer, relancer ou révoquer une invitationPage Membres (Invite Member)
Modifier le rôle ou les groupes d’un membre, suspendre, supprimerLa page du membre
Modifier les rôles, les groupes et la matrice des permissionsParamè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éthodeCheminScopeAction
GET/Usersscim:readLister les membres
POST/Usersscim:writeCréer un membre ; 201 avec Location et ETag
GET/Users/{id}scim:readUn membre, avec son ETag
PUT/Users/{id}scim:writeRemplacer un membre
PATCH/Users/{id}scim:writeModifier certains attributs
DELETE/Users/{id}scim:writeDésprovisionner ; 204
GET, POST/Groupslecture / écritureLister ou créer des groupes
GET, PUT, PATCH, DELETE/Groups/{id}lecture / écritureUn groupe
GET/ServiceProviderConfig, /ResourceTypes, /SchemasaucunDécouverte pour les fournisseurs d’identité

Les réponses et erreurs utilisent Content-Type: application/scim+json.

Correspondance des attributs

Attribut SCIMDans Hermetry
idL’identifiant du membre dans cette organisation
userName, valeur emails principaleL’e-mail du compte
externalIdL’identifiant externe SCIM sur la page du membre (256 caractères maximum)
activeStatut du membre : true Actif, false Inactif
name, displayNameEnregistré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

StatutscimTypeQuand
400invalidFilterUn filtre autre que userName eq ou externalId eq
400invalidSyntax, invalidValueUn corps qui n’est pas du JSON ou qui ne respecte pas le schéma
401aucun« Jeton bearer invalide. » : le jeton est inconnu, expiré, d’une autre organisation ou n’a pas le scope
404aucunAucun membre avec cet identifiant dans votre organisation
409uniquenessL’e-mail est déjà pris, ou le compte existe et n’est pas membre
412aucunIf-Match ne correspond pas à l’ETag actuel du membre
429aucun« Trop de requêtes. Veuillez ralentir. »
501aucunLes 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énementEnvoyé lorsque
member.created, member.updated, member.deletedUn membre est ajouté, modifié ou supprimé
invitation.sent, invitation.accepted, invitation.declined, invitation.revokedUne invitation change d’état
scim.user.provisioned, scim.user.updated, scim.user.deprovisionedVotre fournisseur d’identité a modifié un membre via SCIM