---
title: "Referencia de API SCIM"
description: "Contrato de endpoint SCIM 2.0 para aprovisionar usuarios y grupos en XID.grupos en XID."
locale: "es"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/es/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de API SCIM

## URL base

XID expone API SCIM 2.0 con alcance de organización en `/scim/v2/organizations/{organization_id}`. Los recursos de usuarios y grupos se direccionan con el ID de organización en la ruta.

Configura tu proveedor de identidad con la URL base `https://xid.dev/scim/v2/organizations/{organization_id}` y el token de directorio que se muestra una sola vez cuando creas o rotas el directorio.

```shell
curl https://xid.dev/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'
```

## Autenticación

Las llamadas SCIM usan un token bearer de directorio creado desde la API de administración. XID almacena solo un hash del token y devuelve el token en texto claro una sola vez cuando se crea o se rota.

| Encabezado | Valor | Notas |
| --- | --- | --- |
| `Authorization` | `Bearer scim_xxx` | Requerido para puntos de conexión de usuarios y grupos con alcance de organización. |
| `Content-Type` | `application/scim+json` | Requerido para solicitudes POST, PUT y PATCH. |
| `Accept` | `application/scim+json` | Recomendado para todos los clientes SCIM. |

## Puntos de conexión

| Punto de conexión | Métodos | Uso previsto |
| --- | --- | --- |
| `/scim/v2/ServiceProviderConfig` | `GET` | Respuesta ServiceProviderConfig para el descubrimiento de clientes SCIM. |
| `/scim/v2/Schemas` | `GET` | Metadatos del esquema de usuario y grupo. |
| `/scim/v2/ResourceTypes` | `GET` | Tipos de recursos SCIM compatibles. |
| `/scim/v2/organizations/{organization_id}/Users` | `GET, POST` | Crear y listar usuarios de directorio. |
| `/scim/v2/organizations/{organization_id}/Users/{id}` | `GET, PUT, PATCH, DELETE` | Leer, reemplazar, aplicar parche o desaprovisionar un usuario de directorio. |
| `/scim/v2/organizations/{organization_id}/Groups` | `GET, POST` | Crear y listar grupos de directorio. |
| `/scim/v2/organizations/{organization_id}/Groups/{id}` | `GET, PUT, PATCH, DELETE` | Leer, reemplazar, aplicar parche o eliminar un grupo de directorio. |

## Recurso de usuario

Los recursos de usuario usan `userName` como identificador externo. Los valores de correo, campos de nombre del perfil, estado activo y campos de extensión empresarial se conservan en el perfil SCIM bruto.

| Campo SCIM | Comportamiento de XID |
| --- | --- |
| `id` | ID estable de usuario de directorio XID. |
| `userName` | Requerido. Debe ser único dentro del directorio. |
| `active` | `false` desaprovisiona al usuario y revoca las sesiones activas. |
| `emails` | El correo principal se usa para coincidencias y vinculación de cuentas. |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` | Almacenado y devuelto para atributos empresariales como departamento. |

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}
```

## Recurso de grupo

Los recursos de grupo usan `displayName` como nombre único de grupo de directorio. Los miembros referencian IDs de usuario SCIM y se sincronizan de forma idempotente.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
{ "value": "dir_user_123", "display": "alice@example.com" }
  ]
}
```

## Filtrado, ordenación y paginación

XID admite gramática de filtro SCIM con `and`, `or`, `not` y operadores de comparación (`eq`, `ne`, `co`, `sw`, `ew`, `gt`, `ge`, `lt`, `le`, `pr`). Las expresiones no soportadas devuelven `invalidFilter`. Las listas usan paginación SCIM base 1 con `startIndex`, `count`, `totalResults`, más `sortBy` y `sortOrder` opcionales.

| Consulta | Soporte |
| --- | --- |
| `filter=userName eq "alice@example.com"` | Buscar un usuario por userName. |
| `filter=displayName eq "Engineering"` | Buscar un grupo por displayName. |
| `filter=userName sw "alice" and active eq true` | Combinar operadores lógicos y de comparación. |
| `sortBy=userName&sortOrder=ascending` | Ordenar resultados de listas de usuarios o grupos. |
| `startIndex=1&count=100` | Devolver hasta 100 recursos desde el primer resultado. |
| `attributes=userName,emails.value` | Devuelve solo schemas, id y los atributos SCIM solicitados. |
| `excludedAttributes=emails,meta` | Devuelve el recurso predeterminado sin los atributos SCIM excluidos. |

## Operaciones masivas

`POST /scim/v2/organizations/{organization_id}/Bulk` acepta una `BulkRequest` con hasta 100 operaciones y límite de 1 MiB. Las respuestas devuelven el estado HTTP por operación en una `BulkResponse` aunque algunas fallen.

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
{
  "method": "POST",
  "path": "/Users",
  "bulkId": "user1",
  "data": { "userName": "alice@example.com", "active": true }
}
  ]
}
```

## ETag and If-Match

Las respuestas GET de recursos incluyen `ETag: W/"<meta.version>"` de `meta.version`. `PUT` y `PATCH` requieren encabezado `If-Match` con la versión actual; ausente → `428`, desajuste → `412`.

## Operaciones PATCH

Las solicitudes PATCH usan `urn:ietf:params:scim:api:messages:2.0:PatchOp`. XID admite `add`, `replace` y `remove` para campos de perfil editables y membresías de grupo.

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

## Respuestas de error

Los errores SCIM devuelven `application/scim+json` con el esquema SCIM Error, estado HTTP, detalle y `scimType` opcional.

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "userName already exists"
}
```

## Capacidades de ServiceProviderConfig

- `ServiceProviderConfig` anuncia `sort.supported=true`, `bulk.supported=true` y `etag.supported=true`.
- XID expone endpoints inbound de SCIM Service Provider para IdP externos. Los clientes de push SCIM para SaaS downstream tienen evidencia local con un SaaS simulado, pero la compatibilidad con producción aún requiere una L4 real de administración de SaaS.

## Comportamiento de desaprovisionamiento

- La rotación del token de directorio mantiene válido el token anterior durante una breve ventana de gracia.
- `active=false` y `DELETE /Users/{id}` desaprovisionar al usuario y revocar sesiones activas.
- Las actualizaciones de membresía de grupo son idempotentes. Los miembros desconocidos se pueden resolver después de que el usuario llegue desde el proveedor de identidad.

Source: https://xid.dev/es/scim/index.mdx