SCIM-API-Referenz

Diese Seite dokumentiert die SCIM 2.0-Endpunkte, die axe Account für die Bereitstellung von Benutzern und Gruppen bereitstellt. In den meisten Fällen ruft der SCIM-Connector Ihres Identitätsanbieters diese Endpunkte für Sie auf. Diese Referenz richtet sich an Teams, die eine benutzerdefinierte Integration erstellen oder das Verhalten direkt validieren möchten.

axe implementiert den SCIM-2.0-Standard (RFC 7643 / RFC 7644). Diese Seite konzentriert sich auf das spezifische Verhalten von axe. Für das generische Protokoll konsultieren Sie bitte die SCIM-Spezifikationen.

Basis-URL und Authentifizierung

Alle Endpunkte werden unter /api/scim/v2 auf Ihrer regionalen oder privaten Basis-URL bereitgestellt:

https://axe.deque.com/api/scim/v2

Authentifizieren Sie jede Anfrage mit Ihrem SCIM-API-Schlüssel:

-H "X-API-Key: <API_KEY>"
# or
-H "Authorization: <API_KEY>"

Siehe Voraussetzungen & Einrichtung, um einen Schlüssel und eine Basis-URL zu erhalten.

Konventionen

• Inhaltstyp: application/json
• Fehlerantworten verwenden das SCIM-Fehlerschema:

  {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
    "detail": "<message>",
    "status": <code>
  }

• Paginierung (Benutzer): startIndex (1-basiert) und count (1–100).
• Filterung (Benutzer, Gruppen): filter unter Verwendung des eq Operators, z.B. userName eq "user@example.com".

Benutzer

Benutzer auflisten

GET /api/scim/v2/Users

Gibt Mitglieder Ihres Unternehmens zurück. Unterstützt Paginierung und Filterung.

Abfrageparameter

Beispiel

curl -H "X-API-Key: $KEY" \
  "https://axe.deque.com/api/scim/v2/Users?count=10&startIndex=1"

Antwort 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "5f3e...c2",
      "userName": "user@example.com",
      "active": true,
      "name": { "givenName": "Alex", "familyName": "Doe" },
      "emails": [
        { "primary": true, "value": "user@example.com", "type": "work", "display": "user@example.com" }
      ],
      "groups": [
        { "value": "grp-1", "display": "Axe Monitor", "$ref": "/Groups/grp-1" }
      ],
      "meta": { "resourceType": "User", "location": "/Users/5f3e...c2" }
    }
  ]
}

Fehler

Einen Benutzer abrufen

GET /api/scim/v2/Users/{id}

Gibt einen einzelnen Benutzer anhand seiner axe-Benutzer-ID zurück. active spiegelt die Unternehmensmitgliedschaft wider.

Antwort 200 OK — eine Benutzerressource (siehe oben).

Fehler

Einen Benutzer erstellen

POST /api/scim/v2/Users

Richtet einen Benutzer ein: erstellt das axe-Konto, fügt ihn Ihrem Unternehmen hinzu und sendet eine Einladungs-E-Mail. Ein groups-Wert im Body wird ignoriert — Ordnen Sie den Produktzugriff separat über PATCH /Groups zu.

Anfrage-Body

Beispiel

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "user@example.com",
    "name": { "givenName": "Alex", "familyName": "Doe" },
    "emails": [{ "type": "work", "value": "user@example.com", "primary": true }],
    "active": true
  }' \
  "https://axe.deque.com/api/scim/v2/Users"

Antwort 201 Created — die erstellte Benutzerressource.

Fehler

Einen Benutzer ersetzen

PUT /api/scim/v2/Users/{id}

Aktualisiert den Namen und die E-Mail eines Benutzers.

Anfrageinhalt

Antwort 200 OK — die aktualisierte Benutzerressource.

Fehler

Einen Benutzer aktivieren oder deaktivieren

PATCH /api/scim/v2/Users/{id}

Legt die Unternehmensmitgliedschaft fest. active: true fügt den Benutzer dem Unternehmen hinzu; active: false entzieht ihm die Bereitstellung (entfernt die Mitgliedschaft; das Konto bleibt erhalten).

Anfragetext

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "value": { "active": false } }
  ]
}

Antwort 204 No Content

Fehler

Einen Benutzer entziehen

DELETE /api/scim/v2/Users/{id}

Entfernt den Benutzer aus Ihrem Unternehmen (weiche Entfernung — das Konto bleibt erhalten).

Antwort 204 No Content

Fehler

Gruppen

Gruppen sind entweder Produktabonnements (gewähren einen Produktsitz) oder Teams (organisieren Benutzer). Siehe Wie SCIM mit Axe Konto funktioniert.

Gruppen auflisten

GET /api/scim/v2/Groups

Gibt alle Produktabonnements und Teams für Ihr Unternehmen zurück. Dieser Endpunkt ist nicht paginiert.

Abfrageparameter

Antwort 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "startIndex": 1,
  "itemsPerPage": 5,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "grp-1",
      "displayName": "Axe Monitor",
      "members": [
        { "value": "5f3e...c2", "display": "user@example.com", "$ref": "/Users/5f3e...c2" }
      ]
    }
  ]
}

Eine Gruppe abrufen

GET /api/scim/v2/Groups/{id}

Antwort 200 OK — eine Gruppenressource.

Fehler

Eine Gruppe erstellen

POST /api/scim/v2/Groups

Erstellt ein Team. Wenn displayName genau den Namen eines Produkts entspricht, für das Ihr Unternehmen ein aktives Abonnement hat, wird kein Team erstellt — stattdessen wird die bestehende Produktabonnementgruppe zurückgegeben (201, mit ihren id und Location), und alle members im Anfragetext werden ignoriert. Verwalten Sie die Mitgliedschaft dieser Gruppe über PATCH /Groups/{id}.

Die Übereinstimmung ist groß- und kleinsensitiv und exakt. Wenn der Name mit einem Produkt übereinstimmt, dessen Abonnement nicht aktiv ist, wird stattdessen ein reguläres Team mit diesem Namen erstellt — es wird keine Produktsitze gewähren.

Anfragetext

Antwort 201 Created — die erstellte Gruppenressource, mit einem Location-Header.

Fehler

Gruppenmitgliedschaft aktualisieren

PATCH /api/scim/v2/Groups/{id}

Fügt Mitglieder hinzu oder entfernt sie. Für eine Abonnementgruppe bedeutet dies, dass ein Produktsitz gewährt oder entzogen wird. Für eine Teamgruppe ändert dies die Teammitgliedschaft.

Anfragetext

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "add", "path": "members", "value": [ { "value": "5f3e...c2" } ] }
  ]
}

Verwenden Sie op: "remove" mit einem path, um Mitglieder zu entfernen. Ein replace mit einem leeren Array entfernt alle Mitglieder.

Antwort 204 No Content

Fehler

Eine Gruppe löschen

DELETE /api/scim/v2/Groups/{id}

Löscht ein Team. Löschanforderungen an eine Produkt-Abonnementgruppe werden ignoriert (Rückgabe 204).

Antwort 204 No Content

Fehler

Gruppe aktualisieren (nicht unterstützt)

PUT /api/scim/v2/Groups/{id}

Nicht unterstützt. Gibt 405 Method not allowed zurück. Verwenden Sie PATCH, um die Mitgliedschaft zu ändern.

Erkundungspunkte

Diese unterstützen die automatische Konfiguration des Connectors. Alle geben 200 OK zurück.

Verwandt

• Wie SCIM mit dem axe-Konto funktioniert
• Konfiguration Ihres Identitätsanbieters
• Fehlerbehebung