Referencia de SCIM 2.0

Referencia técnica para los equipos de gestión de identidades que conectan un IdP (Microsoft Entra ID, SailPoint IdentityIQ, …) con mTime: qué atributos y operaciones de SCIM 2.0 admite mTime y qué hace cada uno.

Descripción general


URL base	`https://<tu host de mTime>/api/scim/v2`
Estándares	RFC 7643 (esquema), RFC 7644 (protocolo)
Autenticación	Token de portador (bearer): una clave de API del usuario de servicio de aprovisionamiento del espacio de trabajo (consulta Configurar SCIM con Microsoft Entra ID)
Tipo de contenido	`application/scim+json`
Recursos	`/Users`, `/Groups`
Errores	Respuestas de error SCIM (RFC 7644 §3.12)

Qué gestiona SCIM y qué no

mTime separa el usuario (inicio de sesión, roles, acceso) del empleado y sus contratos:

Usuario → Empleado → n contratos

SCIM gestiona el usuario: quién puede iniciar sesión, con qué nombre y con qué roles. Los empleados y los contratos —unidad organizativa, responsable, condiciones laborales, jornada teórica, fechas de inicio y fin— son datos con fecha sobre los que calcula mTime, y proceden de tu integración de RR. HH., no de SCIM. Un usuario SCIM se vincula con su empleado mediante el externalId (consulta Cómo se aprovisionan los usuarios).

Por eso mTime no admite la Enterprise User Extension: department, manager y employeeNumber son valores únicos sin fecha de vigencia, mientras que un empleado en mTime puede tener varios contratos con fecha.

Usuarios

Atributos

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

Atributo	Lectura	Creación	Actualización	Notas
`id`	✅	—	—	Lo asigna mTime; inmutable
`externalId`	✅	✅	✅	Clave estable (p. ej., número de empleado), única por espacio de trabajo; un duplicado devuelve `409 uniqueness`. Se puede vincular a un atributo de empleado para el emparejamiento
`userName`	✅	✅	⚠️	La dirección de correo del usuario. Solo se puede cambiar mientras el usuario no haya activado su invitación
`emails`	✅	✅	⚠️	Se usa el valor principal (o el primero); misma regla que `userName`. Se devuelve como un único correo principal
`name.givenName`, `name.familyName`	❌	✅	⚠️	Se combinan en el nombre completo, solo cuando se envían juntos (en un mismo objeto `name`, o ambas rutas en el mismo `PATCH`). mTime guarda un único nombre completo y nunca lo divide, así que un `PATCH` con solo uno de ellos se ignora. En la creación y en `PUT`, un nombre o apellido suelto solo se usa cuando no hay `name.formatted` ni `displayName`. No se devuelven en la lectura: el nombre se devuelve como `name.formatted`
`name.formatted`	✅	✅	⚠️	Nombre completo; tiene prioridad sobre nombre/apellido. Una actualización no tiene efecto visible en un usuario vinculado a un empleado salvo que el IdP fije los nombres de los empleados; consulta Qué nombre fija SCIM
`displayName`	✅	✅	⚠️	Nombre completo. Misma regla de actualización que `name.formatted`
`active`	✅	—	✅	`false` suspende al usuario; `true` lo reactiva
`meta.resourceType`, `meta.location`	✅	—	—

Todos los demás atributos de Core User (nickName, title, phoneNumbers, addresses, password, …) y la Enterprise User Extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) no se admiten: se ignoran en la creación y la actualización y nunca se devuelven.

Qué nombre fija SCIM

mTime muestra un solo nombre por persona: el nombre del empleado cuando el usuario está vinculado a un empleado y, si no, el nombre del usuario.

Un usuario vinculado a un empleado muestra el nombre del empleado, que mantiene tu integración de RR. HH. De forma predeterminada, SCIM no actualiza un empleado existente, así que un nombre enviado por SCIM no tiene efecto visible para este usuario. Con Usar los nombres del proveedor de identidad para los empleados activado, cada creación, PUT o PATCH que lleve un nombre lo escribe también en el empleado vinculado; consulta Usar el nombre del proveedor de identidad para los empleados.
Un usuario sin empleado (como un borrador) muestra su propio nombre de usuario. SCIM lo fija al crearlo y puede cambiarlo hasta que la persona active su invitación; después sigue el nombre de su propia cuenta de mTime. Cuando más tarde un rol crea su empleado, este empieza con ese nombre.

Para cambiar el nombre de alguien que es empleado, cámbialo en tu sistema de RR. HH. o, con ese ajuste activado, en tu IdP.

Operaciones

Operación	Compatible	Comportamiento
`POST /Users`	✅	Crea el usuario como invitado y envía el correo de invitación. Es obligatorio un correo (`emails`, o `userName` cuando es una dirección). Lo vincula a un empleado existente si alguno coincide; si no, crea un borrador sin rol, sin empleado y sin invitación. `409` si el `externalId` o el empleado ya están ocupados
`GET /Users/{id}`	✅
`GET /Users?filter=…`	⚠️	Solo `attribute eq "value"`, sobre `userName` o `externalId`. Otros atributos u operadores devuelven `400`. Se combina con la paginación
`GET /Users` (sin filtro)	✅	Todos los usuarios, página a página; consulta Paginación
`PUT /Users/{id}`	✅	Aplica los atributos admitidos indicados arriba
`PATCH /Users/{id}`	⚠️	`add` y `replace` sobre `active`, `userName`, `emails`, `displayName`, `name` (objeto), `name.givenName`, `name.familyName`, `name.formatted`, `externalId`, o sin ruta (recurso parcial). Una ruta puede llevar el prefijo del esquema (`urn:ietf:params:scim:schemas:core:2.0:User:name.givenName`). `remove` y las demás rutas se ignoran
`DELETE /Users/{id}`	✅	Elimina la cuenta de usuario (eliminación lógica) y cierra todas las sesiones. Se conservan el empleado y su historial. Devuelve `204`

Los usuarios con el rol de propietario no se pueden cambiar ni eliminar mediante SCIM (403).

¿Desactivar o eliminar?

	`PATCH active=false`	`DELETE`
Puede iniciar sesión	No: las sesiones se cierran de inmediato	No: las sesiones se cierran de inmediato
Cuenta de usuario	Se conserva, con el estado suspendido	Se elimina (eliminación lógica)
Empleado, registros de tiempo, aprobaciones	Se conservan	Se conservan
Vuelta	`PATCH active=true` restaura el mismo usuario	Un nuevo `POST` crea un usuario nuevo, vinculado al mismo empleado

Grupos

Los grupos se corresponden con roles de mTime: el IdP gestiona la existencia y la pertenencia de un grupo, y los administradores de mTime gestionan los permisos del rol. Consulta Cómo los grupos se convierten en roles.

Atributos

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

Atributo	Lectura	Creación	Actualización	Notas
`id`	✅	—	—	Lo asigna mTime
`externalId`	✅	✅	✅
`displayName`	✅	✅	✅	Se vincula al rol con el mismo nombre o crea un rol personalizado vacío. Cambiarlo cambia el nombre del rol
`members` (`value`, `display`)	✅	✅	✅	`value` es el `id` del usuario SCIM

Operaciones

Operación	Compatible	Comportamiento
`POST /Groups`	✅	Se vincula al rol o lo crea
`GET /Groups/{id}`	✅
`GET /Groups?filter=…`	⚠️	Solo `attribute eq "value"`, sobre `displayName` o `externalId`
`GET /Groups` (sin filtro)	✅	Todos los roles gestionados por el IdP, página a página; consulta Paginación
`PUT /Groups/{id}`	✅	Sustituye el nombre y los miembros
`PATCH /Groups/{id}`	✅	`add`, `replace` y `remove` sobre `members` (incluido `members[value eq "…"]`) y `displayName`
`DELETE /Groups/{id}`	✅	Quita el rol a sus miembros. El rol en sí solo se elimina si ningún administrador llegó a configurarlo

Paginación

GET /Users y GET /Groups admiten paginación por índice (RFC 7644 §3.4.2.4), con o sin filtro.

Parámetro	Predeterminado	Notas
`startIndex`	`1`	Posición del primer resultado, empezando en 1. Los valores menores que 1 cuentan como 1
`count`	`200`	Resultados por página, como máximo 200. `count=0` solo devuelve `totalResults`

La respuesta indica totalResults (todas las coincidencias), startIndex e itemsPerPage (los resultados de esta página). Pide la página siguiente con startIndex + itemsPerPage hasta tener totalResults resultados. Los resultados llegan en un orden fijo, así que las páginas no se saltan ni repiten resultados, salvo que se añadan o eliminen usuarios o grupos entretanto.

Endpoints de descubrimiento

Los tres requieren el mismo token de portador que los demás endpoints SCIM.

Endpoint	Contenido
`GET /ServiceProviderConfig`	Capacidades, que se muestran a continuación
`GET /Schemas`	Esquemas Core `User` y `Group`, limitados a los atributos indicados arriba
`GET /ResourceTypes`	`User` (`/Users`) y `Group` (`/Groups`), sin extensiones de esquema

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

Solución de problemas

Problema	Solución
`400` Unsupported filter	Usa `eq` sobre `userName` o `externalId` (usuarios) o sobre `displayName` o `externalId` (grupos)
`409 uniqueness` al crear	Otro usuario ya tiene este `externalId`, o el empleado ya tiene un usuario. Busca el usuario con `filter=externalId eq "…"` y actualízalo en su lugar
No se ve un cambio de nombre o de apellido	mTime guarda un solo nombre completo y nunca lo divide, así que no puede cambiar solo una mitad. Envía `givenName` y `familyName` juntos en el mismo `PATCH`, o envía `name.formatted` o `displayName`
No se ve un cambio de nombre hecho en el IdP	Es lo esperado para un usuario vinculado a un empleado mientras Usar los nombres del proveedor de identidad para los empleados está desactivado: el nombre que se muestra es el del empleado, que procede de tu integración de RR. HH. Activa el ajuste si el IdP debe fijar los nombres de los empleados; consulta Qué nombre fija SCIM
No se ve un cambio de correo	El usuario ya ha activado su cuenta; su correo de inicio de sesión ya no lo gestiona el aprovisionamiento
`403` en un usuario	El usuario es propietario del espacio de trabajo, y SCIM no puede gestionarlo

Configurar SCIM con Microsoft Entra ID