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:
| Aufgabe | Wo es erledigt wird |
|---|---|
| Mitglieder auflisten, ein Mitglied abrufen, deren Aktivität einsehen | Seite Members |
| Personen einladen, Einladungen erneut senden, erinnern oder widerrufen | Seite Members (Invite Member) |
| Rolle oder Gruppen eines Mitglieds ändern, sperren, entfernen | Die Seite des Mitglieds |
| Rollen, Gruppen und die Berechtigungsmatrix bearbeiten | Settings > Access Control |
| Eigentümerschaft übertragen | In der App (nur Owner) |
| Mitglieder über Ihren Identity Provider anlegen, aktualisieren und deaktivieren | SCIM 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.
| Methode | Pfad | Scope | Funktion |
|---|---|---|---|
| GET | /Users | scim:read | Mitglieder auflisten |
| POST | /Users | scim:write | Ein Mitglied anlegen; 201 mit Location und ETag |
| GET | /Users/{id} | scim:read | Ein Mitglied mit seinem ETag |
| PUT | /Users/{id} | scim:write | Ein Mitglied ersetzen |
| PATCH | /Users/{id} | scim:write | Einzelne Attribute ändern |
| DELETE | /Users/{id} | scim:write | Deprovisionieren; 204 |
| GET, POST | /Groups | Lesen / Schreiben | Gruppen auflisten oder anlegen |
| GET, PUT, PATCH, DELETE | /Groups/{id} | Lesen / Schreiben | Eine Gruppe |
| GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | keiner | Erkennung für Identity Provider |
Antworten und Fehler verwenden Content-Type: application/scim+json.
Wie Attribute abgebildet werden
| SCIM-Attribut | In Hermetry |
|---|---|
id | Die Mitglieds-ID in dieser Organisation |
userName, primärer Wert von emails | Die E-Mail-Adresse des Kontos |
externalId | Die SCIM-External-ID auf der Mitgliedsseite (bis zu 256 Zeichen) |
active | Mitgliedsstatus: true Active, false Inactive |
name, displayName | Wird 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
| Status | scimType | Wann |
|---|---|---|
| 400 | invalidFilter | Ein anderer Filter als userName eq oder externalId eq |
| 400 | invalidSyntax, invalidValue | Ein Body, der kein JSON ist oder das Schema verletzt |
| 401 | keiner | „Invalid bearer token.“: Das Token ist unbekannt, abgelaufen, gehört zu einer anderen Organisation oder hat nicht den nötigen Scope |
| 404 | keiner | Kein Mitglied mit dieser ID in Ihrer Organisation |
| 409 | uniqueness | Die E-Mail ist vergeben, oder das Konto existiert und ist kein Mitglied |
| 412 | keiner | If-Match stimmt nicht mit dem aktuellen ETag des Mitglieds überein |
| 429 | keiner | „Too many requests. Please slow down.“ |
| 501 | keiner | Gruppen 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):
| Ereignis | Gesendet, wenn |
|---|---|
member.created, member.updated, member.deleted | Ein Mitglied hinzugefügt, geändert oder entfernt wird |
invitation.sent, invitation.accepted, invitation.declined, invitation.revoked | Sich der Status einer Einladung ändert |
scim.user.provisioned, scim.user.updated, scim.user.deprovisioned | Ihr Identity Provider ein Mitglied über SCIM geändert hat |

