Referencia de la API SCIM

Esta página es técnica. Describe la API SCIM 2.0 de BreezeAuth para los desarrolladores y los equipos que configuran un sistema de aprovisionamiento o construyen su propio cliente SCIM. BreezeAuth sigue la RFC 7643 (esquemas) y la RFC 7644 (protocolo), con el alcance y los límites que se describen aquí. Lo que cada operación hace con los usuarios y los grupos se explica en Aprovisionar usuarios y Aprovisionar grupos.

URL base y endpoints

Cada organización tiene su propia URL base. Consulta Encuentra tu URL base de SCIM.

https://api.breezeauth.com/organizations/<ID de la organización>/scim/v2

Método	Ruta	Descripción
GET	/ServiceProviderConfig	Las funciones que admite este servidor SCIM.
GET	/ResourceTypes, /ResourceTypes/{name}	Los tipos de recurso: User y Group.
GET	/Schemas, /Schemas/{id}	Los esquemas User (core), Enterprise User y Group (core).
GET	/Users	Listar y filtrar usuarios.
POST	/Users	Crear un usuario.
GET	/Users/{id}	Leer un usuario.
PUT	/Users/{id}	Reemplazar un usuario.
PATCH	/Users/{id}	Cambiar algunos atributos de un usuario.
DELETE	/Users/{id}	Eliminar un usuario.
GET	/Groups	Listar y filtrar grupos.
POST	/Groups	Crear un grupo.
GET	/Groups/{id}	Leer un grupo con sus miembros directos.
PUT	/Groups/{id}	Reemplazar un grupo y sus miembros.
PATCH	/Groups/{id}	Renombrar un grupo, o añadir o quitar miembros.
DELETE	/Groups/{id}	Eliminar un grupo sin miembros.

/Bulk y /Me no están disponibles.

Autenticación

Cada petición debe llevar, en la cabecera Authorization, un token de acceso de un usuario de servicio con el rol Aprovisionador SCIM:

Authorization: Bearer <token de acceso>

Los tokens se obtienen en https://api.breezeauth.com/oauth/token con la concesión client credentials de OAuth 2.0 y la credencial del usuario de servicio. Son de corta duración: solicita uno nuevo antes de que se agote expires_in, o cuando una petición devuelva 401 Unauthorized. Consulta Obtener tokens de acceso para ver el formato de la petición y ejemplos de código.

Todos los controles que se aplican a los usuarios de servicio se aplican también a las peticiones SCIM: la credencial y el usuario de servicio deben estar activos, y la petición debe venir de una red y de un país permitidos si tu organización los restringe.

Peticiones y respuestas

• Envía los cuerpos de las peticiones en JSON, con Content-Type: application/scim+json o application/json.
• Las respuestas usan Content-Type: application/scim+json.
• El atributo schemas es opcional en las peticiones. BreezeAuth siempre lo incluye en las respuestas.
• Las peticiones POST correctas devuelven 201 Created y la dirección del nuevo recurso en la cabecera Location. Las peticiones DELETE correctas devuelven 204 No Content, sin cuerpo.
• Las fechas de meta.created y meta.lastModified están en formato ISO 8601 y en UTC.

Listar y filtrar

GET /Users y GET /Groups devuelven una ListResponse:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 128,
  "startIndex": 1,
  "itemsPerPage": 50,
  "Resources": [{ "id": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "userName": "[email protected]", "…": "…" }]
}

Parámetro	Descripción
filter	Una expresión de igualdad. Consulta más abajo.
startIndex	La posición, empezando en 1, del primer resultado. Por defecto 1.
count	Cuántos resultados por página. Por defecto 50. El máximo es filter.maxResults en /ServiceProviderConfig; los valores mayores se reducen a él.

Filtros

BreezeAuth admite una única expresión de igualdad (eq) sobre estos atributos:

Recurso	Atributos	Ejemplo
Usuarios	userName, externalId	userName eq "[email protected]"
Grupos	displayName, externalId	displayName eq "Equipo de Ventas"

Escapa las comillas dobles y las barras invertidas del valor con una barra invertida, y codifica el filtro entero para URL en la query string. Otros operadores (co, sw, gt…), and, or y not se rechazan con 400 Bad Request y scimType invalidFilter.

Paginación

Los resultados se devuelven en páginas de count elementos. Una página siempre empieza en un múltiplo de count más uno: con count=50, las páginas empiezan en 1, 51, 101 y así sucesivamente. Si pides otro startIndex, BreezeAuth devuelve la página que lo contiene, y el startIndex de la respuesta indica dónde empieza realmente esa página. Para leer todos los resultados, empieza en 1 y suma itemsPerPage a startIndex hasta tener totalResults elementos.

GET /Groups no incluye los miembros. Lee cada grupo con GET /Groups/{id} para obtenerlos.

Seleccionar atributos

Usa attributes para devolver solo algunos atributos, o excludedAttributes para dejar algunos fuera. Ambos reciben una lista separada por comas y no se pueden usar en la misma petición. Funcionan en todas las peticiones que devuelven usuarios o grupos, incluidas POST, PUT y PATCH.

GET /Users?attributes=userName,name.givenName,active
GET /Users?excludedAttributes=urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Los subatributos usan un punto, como en name.givenName. Los atributos de la extensión Enterprise usan la URN completa del esquema como prefijo, como en urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department. schemas, id y meta siempre se devuelven.

Errores

Los errores siguen el formato de error de SCIM:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "email_already_used"
}

Estado	scimType	Significado
400 Bad Request	invalidSyntax	El cuerpo no es un mensaje SCIM válido, por ejemplo un PATCH sin Operations.
400 Bad Request	invalidValue	Falta un valor o no es válido, como un userName ausente, un miembro sin type válido o un cambio de correo que BreezeAuth no permite.
400 Bad Request	invalidFilter	El filtro no es compatible. Consulta Filtros.
400 Bad Request	invalidPath	La ruta del PATCH no es compatible.
400 Bad Request	mutability	El atributo no se puede quitar, como active o userName.
400 Bad Request	tooMany	El grupo tiene más miembros directos de los que SCIM puede devolver.
401 Unauthorized		El token falta, no es válido o ha caducado; la credencial o el usuario de servicio está inactivo; el rol no permite la operación; la petición viene de una red fuera de tus zonas de red; o el usuario es un Propietario.
403 Forbidden		La petición viene de un país que tu organización no permite.
404 Not Found		El usuario, el grupo, el miembro o el esquema no existe en esta organización.
409 Conflict	uniqueness	Otro usuario ya tiene ese userName o externalId, u otro grupo ya tiene ese externalId.
409 Conflict		El grupo todavía tiene miembros y no se puede eliminar.
429 Too Many Requests		Demasiadas peticiones. Consulta Límites de peticiones.
500 Internal Server Error		Un error inesperado. Reintenta más tarde; si persiste, contacta con el soporte de BreezeAuth.

El campo detail contiene un código corto que indica exactamente qué falló. Los más habituales:

detail	Significado
scim_user_name_required	Falta userName o está vacío.
scim_group_display_name_required	Falta displayName o está vacío.
scim_member_type_not_supported	Falta el type de un miembro, o no es User ni Group.
scim_value_invalid	Un valor tiene el tipo o el formato incorrecto, por ejemplo un active que no es booleano.
scim_filter_not_supported	El filtro usa un operador o un atributo no compatible.
scim_attribute_path_invalid	La ruta del PATCH no es compatible, o el atributo no se puede quitar.
scim_operation_invalid	Un PATCH no tiene operaciones, o una operación no es add, replace ni remove.
scim_group_members_limit_exceeded	El grupo tiene demasiados miembros directos para devolverse a través de SCIM.
email_already_used	Otro usuario de la organización ya tiene esa dirección de correo.
scim_external_id_already_used	Otro usuario o, en el caso de un grupo, otro grupo ya tiene ese externalId.
email_address_of_guest_membership_cannot_be_updated	El correo de los invitados no se puede cambiar.
email_address_of_verified_user_to_unverified_domain_cannot_be_updated	El correo de un usuario gestionado solo puede cambiar a otro dominio verificado.
cannot_delete_group_with_assignments	El grupo todavía tiene miembros.

Límites de peticiones

Las peticiones SCIM están limitadas por token de acceso:

Ventana	Peticiones
1 segundo	50
10 segundos	400
30 segundos	1500
1 minuto	4000

Por encima de estos límites, BreezeAuth responde 429 Too Many Requests. Espera un poco y reintenta, aumentando la espera después de cada nuevo 429. La mayoría de los sistemas de aprovisionamiento lo hacen por sí mismos.

Funciones compatibles

GET /ServiceProviderConfig describe estas capacidades en el formato estándar:

Función	Compatible
patch	Sí
filter	Sí, solo igualdad. maxResults es el mayor tamaño de página.
bulk	No
sort	No
etag	No
changePassword	No
authenticationSchemes	OAuth Bearer Token