Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Members-API

Was ein Programm mit den Mitgliedern einer Organisation tun kann: sie über SCIM 2.0 bereitstellen und Änderungen mit Webhooks verfolgen. API-Schlüssel können keine Mitglieder oder Einladungen verwalten.

Diese Seite richtet sich an Administratoren, die die Mitglieder einer Organisation aus einem Programm heraus verwalten möchten. Sie erklärt, was ein API-Schlüssel bei Mitgliedern nicht darf, wie ein Identity Provider Mitglieder über SCIM 2.0 anlegt und entfernt und welche Webhook-Ereignisse Mitgliederänderungen melden.

Was ein API-Schlüssel nicht kann

Mitglieder, Einladungen, Rollen und Gruppen werden nur in der App verwaltet. Kein API-Schlüssel kann diese Routen aufrufen, unabhängig davon, welche Berechtigungen Sie ihm zuweisen wollen:

AufgabeWo es erledigt wird
Mitglieder auflisten, ein Mitglied abrufen, deren Aktivität einsehenSeite Members
Personen einladen, Einladungen erneut senden, erinnern oder widerrufenSeite Members (Invite Member)
Rolle oder Gruppen eines Mitglieds ändern, sperren, entfernenDie Seite des Mitglieds
Rollen, Gruppen und die Berechtigungsmatrix bearbeitenSettings > Access Control
Eigentümerschaft übertragenIn der App (nur Owner)
Mitglieder über Ihren Identity Provider anlegen, aktualisieren und deaktivierenSCIM 2.0 (unten)

Das ist beabsichtigt. Ein Schlüssel kann niemals Berechtigungen aus den Identitäts- und Zugriffsbereichen von Hermetry besitzen: Mitglieder, Einladungen, Organisationseinstellungen, API-Schlüssel, Sitzungen und Anmeldung. Ein kompromittierter Schlüssel darf keine Person hinzufügen, keine Rolle erhöhen und keine externe Adresse einladen. Ein Schlüssel, der eine Mitglieds- oder Einladungsroute aufruft, erhält:

{ "message": "API key does not have the required permission.", "code": "FORBIDDEN" }

mit dem Status 403. Das Annehmen oder Ablehnen einer Einladung erledigt die eingeladene Person selbst, während sie angemeldet ist; Schlüssel funktionieren bei Kontorouten nie. Die vollständige Regel finden Sie unter Authentication.

Mitglieder mit SCIM 2.0 bereitstellen

SCIM ermöglicht es Ihrem Identity Provider, Mitglieder anzulegen, zu aktualisieren und zu deaktivieren. Die Einrichtung in der App (Endpunkt und SCIM-Token) finden Sie unter Single Sign-on (SAML) und Provisioning. Dieser Abschnitt ist die Routenreferenz für eine Integration, die SCIM selbst aufruft.

Alle SCIM-Pfade liegen unter https://<your host>/tenant/<tenantId>/api/scim/v2. Senden Sie das SCIM-Token in Authorization: Bearer <token>. Lesezugriffe benötigen den Scope scim:read, Schreibzugriffe den Scope scim:write. Das Token muss zu der Organisation im Pfad gehören.

MethodePfadScopeFunktion
GET/Usersscim:readMitglieder auflisten
POST/Usersscim:writeEin Mitglied anlegen; 201 mit Location und ETag
GET/Users/{id}scim:readEin Mitglied mit seinem ETag
PUT/Users/{id}scim:writeEin Mitglied ersetzen
PATCH/Users/{id}scim:writeEinzelne Attribute ändern
DELETE/Users/{id}scim:writeDeprovisionieren; 204
GET, POST/GroupsLesen / SchreibenGruppen auflisten oder anlegen
GET, PUT, PATCH, DELETE/Groups/{id}Lesen / SchreibenEine Gruppe
GET/ServiceProviderConfig, /ResourceTypes, /SchemaskeinerErkennung für Identity Provider

Antworten und Fehler verwenden Content-Type: application/scim+json.

Wie Attribute abgebildet werden

SCIM-AttributIn Hermetry
idDie Mitglieds-ID in dieser Organisation
userName, primärer Wert von emailsDie E-Mail-Adresse des Kontos
externalIdDie SCIM-External-ID auf der Mitgliedsseite (bis zu 256 Zeichen)
activeMitgliedsstatus: true Active, false Inactive
name, displayNameWird gespeichert, wenn Keep names in step aktiviert ist (Standard) und das Konto nur zu Ihrer Organisation gehört

Ein neues Mitglied erhält die SCIM-Standardrolle (User, sofern Sie sie nicht in den SCIM-Einstellungen ändern). Rollen aus Gruppen werden unter Groups and roles festgelegt.

Listen

GET /Users liest startIndex (ab 1), count (Standard 100, höchstens 200), sortBy und sortOrder (ascending oder descending). Die einzigen Filter sind die Gleichheit bei userName oder externalId:

GET /Users?filter=userName eq "ana@example.com"
GET /Users?filter=externalId eq "00u1a2b3c4"

Jeder andere Filter antwortet mit 400 und scimType invalidFilter.

Regeln beim Anlegen

  • Eine neue E-Mail-Adresse legt das Konto und das Mitglied an.
  • Ein Konto, das bereits existiert, aber kein Mitglied Ihrer Organisation ist, wird mit 409 (uniqueness) abgelehnt: „An account with that userName already exists and is not a member of this organization. It joins by invitation.“ Laden Sie die Person zuerst in der App ein; danach verwaltet SCIM die Mitgliedschaft.

Änderungen durch andere

GET /Users/{id} liefert einen ETag. Senden Sie ihn in If-Match bei PUT, PATCH oder DELETE; wurde das Mitglied inzwischen geändert, lautet die Antwort 412. If-None-Match bei einem GET antwortet mit 304, wenn sich nichts geändert hat.

Gruppen

Gruppenrouten antworten mit 501 („SCIM Groups are not enabled for this tenant.“), bis Gruppen in den SCIM-Einstellungen aktiviert werden. Ist Groups aktiv, folgt die Rolle eines Mitglieds den Gruppen, die Rollen zugeordnet sind. Der letzte aktive Owner wird durch eine Gruppenänderung niemals herabgestuft.

Beispiel

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, "…": "…" } ]
}

SCIM-Fehler

StatusscimTypeWann
400invalidFilterEin anderer Filter als userName eq oder externalId eq
400invalidSyntax, invalidValueEin Body, der kein JSON ist oder das Schema verletzt
401keiner„Invalid bearer token.“: Das Token ist unbekannt, abgelaufen, gehört zu einer anderen Organisation oder hat nicht den nötigen Scope
404keinerKein Mitglied mit dieser ID in Ihrer Organisation
409uniquenessDie E-Mail ist vergeben, oder das Konto existiert und ist kein Mitglied
412keinerIf-Match stimmt nicht mit dem aktuellen ETag des Mitglieds überein
429keiner„Too many requests. Please slow down.“
501keinerGruppen sind nicht aktiviert

Mitgliederänderungen mit Webhooks verfolgen

Damit ein anderes System ohne Polling synchron bleibt, abonnieren Sie einen Webhook für diese Ereignisse (siehe Webhooks):

EreignisGesendet, wenn
member.created, member.updated, member.deletedEin Mitglied hinzugefügt, geändert oder entfernt wird
invitation.sent, invitation.accepted, invitation.declined, invitation.revokedSich der Status einer Einladung ändert
scim.user.provisioned, scim.user.updated, scim.user.deprovisionedIhr Identity Provider ein Mitglied über SCIM geändert hat