SCIM 2.0-referentie

Technische referentie voor identity-managementteams die een IdP (Microsoft Entra ID, SailPoint IdentityIQ, …) aan mTime koppelen: welke SCIM 2.0-attributen en -bewerkingen mTime ondersteunt, en wat elk ervan doet.

Overzicht


Basis-URL	`https://<your mTime host>/api/scim/v2`
Standaarden	RFC 7643 (schema), RFC 7644 (protocol)
Authenticatie	Bearer-token: een API-sleutel van de provisioning-servicegebruiker van de workspace (zie SCIM instellen met Microsoft Entra ID)
Mediatype	`application/scim+json`
Resources	`/Users`, `/Groups`
Fouten	SCIM-foutresponses (RFC 7644 §3.12)

Wat SCIM beheert, en wat niet

mTime maakt onderscheid tussen de gebruiker (aanmelding, rollen, toegang) en de medewerker met zijn dienstverbanden:

Gebruiker → Medewerker → n dienstverbanden

SCIM beheert de gebruiker: wie zich mag aanmelden, onder welke naam en met welke rollen. Medewerkers en dienstverbanden — organisatie-eenheid, manager, arbeidsvoorwaarden, werktijdnorm, begin- en einddatum — zijn gedateerde gegevens waarmee mTime rekent, en ze komen uit je HR-integratie, niet uit SCIM. Een SCIM-gebruiker wordt via de externalId aan zijn medewerker gekoppeld (zie Hoe gebruikers worden geprovisioned).

Daarom ondersteunt mTime de Enterprise User Extension niet: department, manager en employeeNumber zijn daarin losse waarden zonder geldigheidsdatum, terwijl een medewerker in mTime meerdere gedateerde dienstverbanden kan hebben.

Gebruikers

Attributen

Schema urn:ietf:params:scim:schemas:core:2.0:User.

Attribuut	Lezen	Aanmaken	Bijwerken	Opmerkingen
`id`	✅	—	—	Toegekend door mTime, onwijzigbaar
`externalId`	✅	✅	✅	Stabiele sleutel (bijv. personeelsnummer), uniek per workspace; een duplicaat geeft `409 uniqueness`. Kan aan een medewerkerattribuut worden gekoppeld om de medewerker te vinden
`userName`	✅	✅	⚠️	Het e-mailadres van de gebruiker. Alleen te wijzigen zolang de gebruiker zijn uitnodiging nog niet heeft geactiveerd
`emails`	✅	✅	⚠️	De primaire (of eerste) waarde wordt gebruikt; dezelfde regel als voor `userName`. Wordt teruggegeven als één primair e-mailadres
`name.givenName`, `name.familyName`	❌	✅	⚠️	Samengevoegd tot de volledige naam — alleen als beide samen worden gestuurd (in één `name`-object, of beide paden in dezelfde `PATCH`). mTime slaat één volledige naam op en splitst die nooit, dus een `PATCH` met maar één van beide wordt genegeerd. Bij aanmaken en `PUT` wordt een losse voor- of achternaam alleen gebruikt als er geen `name.formatted` of `displayName` is. Niet teruggegeven bij lezen: de naam komt terug als `name.formatted`
`name.formatted`	✅	✅	⚠️	Volledige naam; gaat voor voor- en achternaam. Een wijziging heeft geen zichtbaar effect voor een gebruiker die aan een medewerker is gekoppeld, tenzij de IdP de namen van medewerkers bepaalt — zie Welke naam SCIM instelt
`displayName`	✅	✅	⚠️	Volledige naam. Zelfde regel voor wijzigingen als `name.formatted`
`active`	✅	—	✅	`false` schorst de gebruiker; `true` heractiveert
`meta.resourceType`, `meta.location`	✅	—	—

Alle andere Core User-attributen (nickName, title, phoneNumbers, addresses, password, …) en de Enterprise User Extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) worden niet ondersteund: ze worden bij aanmaken en bijwerken genegeerd en nooit teruggegeven.

Welke naam SCIM instelt

mTime toont één naam voor een persoon: de naam van de medewerker als de gebruiker aan een medewerker is gekoppeld, anders de naam van de gebruiker.

Een gebruiker die aan een medewerker is gekoppeld toont de naam van de medewerker, die je HR-integratie bijhoudt. Standaard werkt SCIM een bestaande medewerker niet bij, dus een naam via SCIM heeft voor deze gebruiker geen zichtbaar effect. Staat Namen van de identiteitsprovider gebruiken als medewerkernamen aan, dan zet elke aanmaak, PUT of PATCH met een naam die naam ook op de gekoppelde medewerker — zie De naam uit de identiteitsprovider voor medewerkers gebruiken.
Een gebruiker zonder medewerker (zoals een concept) toont de eigen gebruikersnaam. SCIM stelt die in bij het aanmaken en kan die wijzigen tot de persoon de uitnodiging activeert; daarna volgt die de naam op het eigen mTime-account. Maakt een rol later de medewerker aan, dan begint die met deze naam.

Wijzig de naam in je HR-systeem om een medewerker te hernoemen — of in je IdP als die instelling aanstaat.

Bewerkingen

Bewerking	Ondersteund	Gedrag
`POST /Users`	✅	Maakt de gebruiker aan als uitgenodigd en verstuurt de uitnodigingsmail. Een e-mailadres is verplicht (`emails`, of `userName` als dat een adres is). Koppelt aan een bestaande medewerker als er een overeenkomt; anders wordt een concept aangemaakt zonder rol, zonder medewerker en zonder uitnodiging. `409` als de `externalId` of de medewerker al in gebruik is
`GET /Users/{id}`	✅
`GET /Users?filter=…`	⚠️	Alleen `attribute eq "value"`, op `userName` of `externalId`. Andere attributen of operatoren geven `400`. Te combineren met paginering
`GET /Users` (zonder filter)	✅	Alle gebruikers, pagina voor pagina — zie Paginering
`PUT /Users/{id}`	✅	Past de hierboven ondersteunde attributen toe
`PATCH /Users/{id}`	⚠️	`add` en `replace` op `active`, `userName`, `emails`, `displayName`, `name` (object), `name.givenName`, `name.familyName`, `name.formatted`, `externalId`, of zonder pad (gedeeltelijke resource). Een pad mag het schemavoorvoegsel bevatten (`urn:ietf:params:scim:schemas:core:2.0:User:name.givenName`). `remove` en andere paden worden genegeerd
`DELETE /Users/{id}`	✅	Verwijdert het gebruikersaccount (zachte verwijdering) en beëindigt alle sessies. De medewerker en zijn geschiedenis blijven bewaard. Geeft `204` terug

Gebruikers met de rol owner kunnen niet via SCIM worden gewijzigd of verwijderd (403).

Uitschakelen of verwijderen?

	`PATCH active=false`	`DELETE`
Kan zich aanmelden	Nee — sessies worden direct beëindigd	Nee — sessies worden direct beëindigd
Gebruikersaccount	Blijft bestaan, status geschorst	Verwijderd (zachte verwijdering)
Medewerker, tijdregistraties, goedkeuringen	Blijven bewaard	Blijven bewaard
Terugkeer	`PATCH active=true` herstelt dezelfde gebruiker	Een nieuwe `POST` maakt een nieuwe gebruiker aan, gekoppeld aan dezelfde medewerker

Groepen

Groepen komen overeen met mTime-rollen: de IdP bepaalt of een groep bestaat en wie er lid van is, mTime-beheerders bepalen de machtigingen van de rol. Zie Hoe groepen rollen worden.

Attributen

Schema urn:ietf:params:scim:schemas:core:2.0:Group.

Attribuut	Lezen	Aanmaken	Bijwerken	Opmerkingen
`id`	✅	—	—	Toegekend door mTime
`externalId`	✅	✅	✅
`displayName`	✅	✅	✅	Koppelt aan de rol met dezelfde naam, of maakt een lege aangepaste rol aan. Een nieuwe groepsnaam hernoemt ook de rol
`members` (`value`, `display`)	✅	✅	✅	`value` is de SCIM-`id` van de gebruiker

Bewerkingen

Bewerking	Ondersteund	Gedrag
`POST /Groups`	✅	Koppelt aan de rol of maakt die aan
`GET /Groups/{id}`	✅
`GET /Groups?filter=…`	⚠️	Alleen `attribute eq "value"`, op `displayName` of `externalId`
`GET /Groups` (zonder filter)	✅	Alle door de IdP beheerde rollen, pagina voor pagina — zie Paginering
`PUT /Groups/{id}`	✅	Vervangt naam en leden
`PATCH /Groups/{id}`	✅	`add`, `replace` en `remove` op `members` (inclusief `members[value eq "…"]`) en `displayName`
`DELETE /Groups/{id}`	✅	Ontneemt de leden de rol. De rol zelf wordt alleen verwijderd als geen beheerder hem ooit heeft geconfigureerd

Paginering

GET /Users en GET /Groups ondersteunen paginering op index (RFC 7644 §3.4.2.4), met of zonder filter.

Parameter	Standaard	Opmerkingen
`startIndex`	`1`	Positie (vanaf 1) van het eerste resultaat. Waarden onder 1 tellen als 1
`count`	`200`	Resultaten per pagina, maximaal 200. `count=0` geeft alleen `totalResults` terug

Het antwoord geeft totalResults (alle overeenkomsten), startIndex en itemsPerPage (de resultaten op deze pagina). Vraag de volgende pagina op met startIndex + itemsPerPage tot je totalResults resultaten hebt. De resultaten komen in een vaste volgorde, dus pagina’s slaan geen resultaten over en herhalen er geen, tenzij er tussendoor gebruikers of groepen worden aangemaakt of verwijderd.

Discovery-endpoints

Alle drie vereisen hetzelfde bearer-token als de andere SCIM-endpoints.

Endpoint	Inhoud
`GET /ServiceProviderConfig`	Mogelijkheden, zie hieronder
`GET /Schemas`	De Core-schema’s `User` en `Group`, beperkt tot de attributen hierboven
`GET /ResourceTypes`	`User` (`/Users`) en `Group` (`/Groups`), zonder schema-extensies

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "https://help.mtime.app",
  "patch": { "supported": true },
  "bulk": { "supported": false, "maxOperations": 0, "maxPayloadSize": 0 },
  "filter": { "supported": true, "maxResults": 200 },
  "changePassword": { "supported": false },
  "sort": { "supported": false },
  "etag": { "supported": false },
  "authenticationSchemes": [
    {
      "type": "oauthbearertoken",
      "name": "OAuth Bearer Token",
      "description": "Bearer token issued for the workspace's provisioning service user",
      "primary": true
    }
  ]
}

Problemen oplossen

Probleem	Oplossing
`400` Unsupported filter	Gebruik `eq` op `userName` of `externalId` (gebruikers) of op `displayName` of `externalId` (groepen)
`409 uniqueness` bij aanmaken	Een andere gebruiker heeft deze `externalId` al, of de medewerker heeft al een gebruiker. Zoek de gebruiker op met `filter=externalId eq "…"` en werk die bij in plaats van een nieuwe aan te maken
Een gewijzigde voor- of achternaam is niet zichtbaar	mTime slaat één volledige naam op en splitst die nooit, dus het kan niet één helft wijzigen. Stuur `givenName` en `familyName` samen in dezelfde `PATCH`, of stuur `name.formatted` of `displayName`
Een naamswijziging vanuit de IdP is niet zichtbaar	Verwacht voor een gebruiker die aan een medewerker is gekoppeld zolang Namen van de identiteitsprovider gebruiken als medewerkernamen uit staat: de getoonde naam is die van de medewerker, en die komt uit je HR-integratie. Zet de instelling aan als de IdP de namen van medewerkers moet bepalen — zie Welke naam SCIM instelt
Een gewijzigd e-mailadres is niet zichtbaar	De gebruiker heeft zijn account al geactiveerd; zijn aanmeld-e-mailadres wordt niet meer door de provisioning beheerd
`403` op een gebruiker	De gebruiker is eigenaar van de workspace, en die kan SCIM niet beheren

SCIM instellen met Microsoft Entra ID