Aprovisionar usuarios con SCIM

A través del endpoint /Users, un sistema de aprovisionamiento gestiona a las personas de tu organización: los usuarios que ves en Usuarios › Usuarios humanos en la consola de administración. Esta página explica qué hace en BreezeAuth cada operación SCIM. Los detalles del protocolo comunes a usuarios y grupos, como la autenticación, los filtros, la paginación y los errores, están en la referencia de la API SCIM.

Todas las rutas de abajo son relativas a la URL base de SCIM de tu organización.

Qué es un usuario SCIM

Cada usuario SCIM es un usuario de tu organización. Su id es el identificador del usuario en BreezeAuth, el mismo valor que la API de BreezeAuth llama membershipsUuid y que incluyen los eventos de webhook. Úsalo para leer, actualizar o eliminar el usuario, y para añadirlo a grupos.

Los usuarios de servicio no son personas: /Users nunca los devuelve y no se pueden cambiar a través de SCIM.

Cómo se corresponden los atributos SCIM con BreezeAuth

Atributo SCIM	En BreezeAuth
userName	Correo, la dirección con la que la persona inicia sesión. Obligatorio y único en la organización.
name.givenName	Nombre
name.familyName	Apellido
displayName	Sirve para rellenar el nombre y el apellido cuando falta name. Se devuelve como el nombre completo.
active	Estado: true para Activo, false para Inactivo. Consulta Estados.
externalId	El identificador de la persona en el sistema de aprovisionamiento. BreezeAuth lo guarda, pero no aparece en la consola. Único en la organización.
title	Cargo
emails	La dirección distinta de userName, si la hay, se guarda como correo secundario.
phoneNumbers con type work	Teléfono del trabajo
phoneNumbers con type mobile	Teléfono
addresses	La dirección work o, si no la hay, la primera con datos: streetAddress, locality (ciudad), region (estado) y postalCode.
photos	La foto de perfil de la persona, a partir de la primera URL.
employeeNumber (extensión Enterprise)	ID de empleado
costCenter (extensión Enterprise)	Centro de costes
organization (extensión Enterprise)	Unidad organizativa
department (extensión Enterprise)	Departamento
manager.value (extensión Enterprise)	El responsable de la persona, como el id SCIM de otro usuario.

Los atributos de la extensión Enterprise van dentro del objeto urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Otros atributos, como password, roles, groups o locale, se ignoran: los grupos de un usuario se gestionan a través de /Groups, y los roles solo en la consola de administración.

Crear un usuario

POST /Users
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "[email protected]",
  "externalId": "00u1a2b3c4",
  "name": { "givenName": "Ana", "familyName": "Souza" },
  "title": "Gestora de cuentas",
  "phoneNumbers": [{ "value": "+55 11 99999-9999", "type": "mobile" }],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "4021",
    "department": "Ventas"
  }
}

BreezeAuth responde 201 Created con el nuevo usuario, y su dirección en la cabecera Location:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d",
  "userName": "[email protected]",
  "externalId": "00u1a2b3c4",
  "name": { "givenName": "Ana", "familyName": "Souza", "formatted": "Ana Souza" },
  "displayName": "Ana Souza",
  "active": true,
  "title": "Gestora de cuentas",
  "emails": [{ "value": "[email protected]", "type": "work", "primary": true }],
  "phoneNumbers": [{ "value": "+55 11 99999-9999", "type": "mobile" }],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "4021",
    "department": "Ventas"
  },
  "meta": {
    "resourceType": "User",
    "created": "2026-10-13T14:32:05.000Z",
    "lastModified": "2026-10-13T14:32:05.000Z",
    "location": "https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2/Users/a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d"
  }
}

userName es obligatorio. Si falta name, BreezeAuth divide displayName en nombre y apellido y, como último recurso, usa la parte del correo anterior a la @.

Lo que ocurre después depende de la dirección de correo, exactamente igual que cuando un administrador añade un usuario:

Dirección de correo	Resultado
De uno de tus dominios verificados	Un usuario gestionado, Activo desde el primer momento. La persona recibe un correo de bienvenida.
De cualquier otro dominio	Un invitado, Pendiente hasta que acepte la invitación que recibe por correo. Hasta entonces, SCIM lo devuelve con active: false. Consulta Invitaciones.

Si active es false en la petición, el usuario se crea y se desactiva inmediatamente.

Buscar y leer usuarios

Petición	Devuelve
GET /Users/{id}	Un usuario.
GET /Users	Todos los usuarios de la organización, página a página.
GET /Users?filter=userName eq "[email protected]"	El usuario con esa dirección de correo, si existe.
GET /Users?filter=externalId eq "00u1a2b3c4"	El usuario con ese identificador externo, si existe.

Los sistemas de aprovisionamiento suelen buscar con uno de estos filtros antes de crear un usuario, para evitar duplicados. Recuerda codificar el filtro para URL en la query string. La paginación y los demás parámetros se describen en la referencia.

Cómo aparecen los estados

SCIM solo sabe si un usuario está activo. Los estados de BreezeAuth aparecen así:

Estado en BreezeAuth	active
Activo	true
Inactivo, Pendiente, Invitación rechazada, Revisión pendiente	false

Actualizar un usuario

Reemplazar un usuario (PUT)

PUT /Users/{id} reemplaza el usuario entero por el cuerpo que envías, que tiene el mismo formato que en la creación. Todo atributo que dejes fuera se borra en BreezeAuth y, si active queda fuera, el usuario pasa a ser Activo. Envía el usuario completo cada vez, o usa PATCH para cambiar solo algunos atributos.

Cambiar algunos atributos (PATCH)

PATCH /Users/{id} aplica una lista de operaciones, según el estándar SCIM:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "title", "value": "Directora de ventas" },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
      "value": "Comercial"
    },
    { "op": "remove", "path": "phoneNumbers[type eq \"mobile\"].value" }
  ]
}

Cada operación tiene un op (add, replace o remove), un path y, salvo en remove, un value. Las rutas compatibles son:

Ruta	add / replace	remove
active	Sí	No
userName o emails[type eq "work"].value	Sí	No
name.givenName, name.familyName	Sí	No
displayName (dividido en nombre y apellido)	Sí	No
externalId	Sí	Sí
title	Sí	Sí
phoneNumbers[type eq "work"].value, phoneNumbers[type eq "mobile"].value	Sí	Sí
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User: seguido de employeeNumber, costCenter, organization, department, manager o manager.value	Sí	Sí

Una operación add o replace también puede omitir path y enviar un objeto en value, por ejemplo { "op": "replace", "value": { "active": false } }. De esa forma, BreezeAuth acepta active, userName, externalId, name, displayName, title y el objeto de la extensión Enterprise. Las direcciones, los correos secundarios y las fotos solo se pueden cambiar con PUT.

Todas las operaciones de una petición se aplican juntas: si una de ellas no es válida, no se cambia nada.

Cambiar la dirección de correo de un usuario

Cambiar userName sigue las mismas reglas que en la consola de administración:

• Usuarios gestionados: la nueva dirección debe ser de uno de tus dominios verificados. La cuenta de BreezeAuth de la persona también se actualiza.
• Invitados: la dirección de correo no se puede cambiar, y la petición falla con 400 Bad Request. Para pasar a un invitado a una nueva dirección, crea un nuevo usuario y elimina el antiguo.

Desactivar un usuario

Para quitarle el acceso a alguien y conservar su registro, establece active en false:

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

El usuario pasa a ser Inactivo, con el mismo efecto que desactivarlo en la consola de administración: un usuario gestionado ya no puede iniciar sesión en BreezeAuth, y un invitado ya no puede usar las aplicaciones de tu organización. Sus grupos y asignaciones de aplicaciones se conservan. Vuelve a establecer active en true para restaurar el acceso.

Eliminar un usuario

DELETE /Users/{id}

BreezeAuth responde 204 No Content. Igual que al eliminarlo en la consola de administración, el usuario se quita de todos sus grupos y aplicaciones y, en el caso de un usuario gestionado, también se elimina su cuenta de BreezeAuth. Esto no se puede deshacer.

Lo que SCIM no puede cambiar

• Propietarios. Los usuarios con el rol Propietario no se pueden cambiar ni eliminar a través de SCIM: la petición falla con 401 Unauthorized. Gestiónalos en la consola de administración.
• Roles. SCIM nunca da ni quita roles administrativos.
• Estados distintos de activo e inactivo. Un sistema de aprovisionamiento no puede devolver un usuario a Pendiente ni a Revisión pendiente.
• Contraseñas, MFA y sesiones. Pertenecen a la persona y a las herramientas de seguridad de la cuenta de tu organización.