SCIM API-referentie

Deze pagina documenteert de SCIM 2.0 endpoints die axe Account beschikbaar stelt voor gebruikers- en groepsvoorziening. In de meeste gevallen roept de SCIM-connector van je identiteitsprovider deze endpoints namens jou aan; deze referentie is voor teams die een aangepaste integratie bouwen of gedrag rechtstreeks willen valideren.

axe implementeert de SCIM 2.0-standaard (RFC 7643 / RFC 7644). Deze pagina richt zich op axe-specifiek gedrag. Voor het generieke protocol, raadpleeg de SCIM-specificaties.

Basis-URL en authenticatie

Alle endpoints worden aangeboden onder /api/scim/v2 op je regionale of privé-basis-URL:

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

Authenticeer elke aanvraag met je SCIM-API-sleutel:

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

Zie Vereisten en setup om een sleutel en basis-URL te verkrijgen.

Conventies

• Contenttype: application/json
• Foutreacties gebruiken het SCIM-foutschema:

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

• Paginering (Gebruikers): startIndex (1-gebaseerd) en count (1–100).
• Filteren (Gebruikers, Groepen): filter met behulp van de eq operator, bijv. userName eq "user@example.com".

Gebruikers

Gebruikerslijst

GET /api/scim/v2/Users

Geeft leden van je onderneming terug. Ondersteunt paginering en filteren.

Queryparameters

Voorbeeld

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

Antwoord 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" }
    }
  ]
}

Fouten

Haal een gebruiker op

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

Geeft een enkele gebruiker terug op basis van hun axe-gebruikers-ID. active weerspiegelt ondernemingslidmaatschap.

Antwoord 200 OK — een Gebruikersbron (zie hierboven).

Fouten

Maak een gebruiker aan

POST /api/scim/v2/Users

Voorziet een gebruiker: maakt het axe-account aan, voegt hen toe aan je onderneming, en stuurt een uitnodigingsmail. Een groups waarde in de body wordt genegeerd — wijs producttoegang apart toe via PATCH /Groups.

Aanvraagbody

Voorbeeld

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"

Antwoord 201 Created — de aangemaakte Gebruikersbron.

Fouten

Een gebruiker vervangen

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

Wijzigt de naam en het e-mailadres van een gebruiker.

Verzoekbody

Antwoord 200 OK — de bijgewerkte Gebruikersbron.

Fouten

Een gebruiker activeren of deactiveren

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

Stelt het ondernemingslidmaatschap in. active: true voegt de gebruiker toe aan de onderneming; active: false deactiveert hen (verwijdert lidmaatschap; het account wordt behouden).

Verzoeksbody

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

Antwoord 204 No Content

Fouten

Een gebruiker deactiveren

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

Verwijdert de gebruiker uit uw onderneming (zachte verwijdering — het account wordt behouden).

Antwoord 204 No Content

Fouten

Groepen

Groepen zijn ofwel productabonnementen (verlenen een productstoel) of teams (organiseren gebruikers). Zie Hoe SCIM werkt met axe-account.

Groepen weergeven

GET /api/scim/v2/Groups

Geeft alle productabonnementen en teams voor uw onderneming weer. Dit eindpunt is niet gepagineerd.

Queryparameters

Antwoord 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" }
      ]
    }
  ]
}

Een groep ophalen

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

Antwoord 200 OK — een groep resource.

Fouten

Een groep aanmaken

POST /api/scim/v2/Groups

Maakt een team. Als displayName exact overeenkomt met de naam van een product waarvoor uw onderneming een actief abonnement heeft, wordt er geen team aangemaakt — in plaats daarvan wordt de bestaande productabonnements-groep geretourneerd (201, met zijn id en Location), en worden eventuele members in de verzoeksbody genegeerd. Beheer dat groepslidmaatschap via PATCH /Groups/{id}.

Matching is hoofdlettergevoelig en exact. Als de naam overeenkomt met een product waarvan het abonnement niet actief is, wordt er in plaats daarvan een regulier team met die naam aangemaakt — het zal geen productstoelen verlenen.

Verzoeksbody

Antwoord 201 Created — de aangemaakte Groep-resource, met een Location header.

Fouten

Groepslidmaatschap bijwerken

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

Voegt leden toe of verwijdert ze. Voor een abonnementsroep verleent of herroept dit een productplaats. Voor een teamgroep wijzigt dit het teamlidmaatschap.

Aanvraagbody

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

Gebruik op: "remove" met een path om leden te verwijderen. Een replace met een lege array verwijdert alle leden.

Antwoord 204 No Content

Fouten

Een groep verwijderen

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

Verwijdert een team. Verwijderingsverzoeken voor een productabonnementsroep worden genegeerd (retourneert 204).

Antwoord 204 No Content

Fouten

Een groep bijwerken (niet ondersteund)

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

Niet ondersteund. Retourneert 405 Method not allowed. Gebruik PATCH om lidmaatschap te wijzigen.

Ontdekkingseindpunten

Deze ondersteunen automatische connectorconfiguratie. Allemaal retourneren 200 OK.

Verwante informatie

• Hoe SCIM werkt met een Axe-account
• Uw Identity Provider configureren
• Probleemoplossing