Referencia de la API SCIM

Esta página documenta los endpoints de SCIM 2.0 que axe Account expone para la provisión de usuarios y grupos. En la mayoría de los casos, el conector SCIM de su proveedor de identidad llama a estos endpoints por usted; esta referencia es para equipos que construyen una integración personalizada o validan el comportamiento directamente.

axe implementa el estándar SCIM 2.0 (RFC 7643 / RFC 7644). Esta página se centra en el comportamiento específico de axe. Para el protocolo genérico, consulte las especificaciones de SCIM.

URL base y autenticación

Todos los endpoints se sirven bajo /api/scim/v2 en su URL base regional o privada:

https://axe.deque.com/api/scim/v2

Autentique cada solicitud con su clave de API SCIM:

-H "X-API-Key: <API_KEY>"
# or
-H "Authorization: <API_KEY>"

Consulte Requisitos previos y configuración para obtener una clave y URL base.

Convenciones

• Tipo de contenido: application/json
• Respuestas de errores usan el esquema de error SCIM:

  {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
    "detail": "<message>",
    "status": <code>
  }

• Paginación (Usuarios): startIndex (basado en 1) y count (1–100).
• Filtrado (Usuarios, Grupos): filter usando el operador eq, por ejemplo, userName eq "user@example.com".

Usuarios

Listar usuarios

GET /api/scim/v2/Users

Devuelve miembros de su empresa. Soporta paginación y filtrado.

Parámetros de consulta

Ejemplo

curl -H "X-API-Key: $KEY" \
  "https://axe.deque.com/api/scim/v2/Users?count=10&startIndex=1"

Respuesta 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "5f3e...c2",
      "userName": "user@example.com",
      "active": true,
      "name": { "givenName": "Alex", "familyName": "Doe" },
      "emails": [
        { "primary": true, "value": "user@example.com", "type": "work", "display": "user@example.com" }
      ],
      "groups": [
        { "value": "grp-1", "display": "Axe Monitor", "$ref": "/Groups/grp-1" }
      ],
      "meta": { "resourceType": "User", "location": "/Users/5f3e...c2" }
    }
  ]
}

Errores

Obtener un usuario

GET /api/scim/v2/Users/{id}

Devuelve un único usuario por su ID de usuario de axe. active refleja la membresía empresarial.

Respuesta 200 OK — un recurso de Usuario (ver arriba).

Errores

Crear un usuario

POST /api/scim/v2/Users

Provisiones de un usuario: crea la cuenta de axe, lo agrega a su empresa y envía un correo de invitación. Un valor groups en el cuerpo se ignora — asigne el acceso al producto por separado a través de PATCH /Groups.

Cuerpo de la solicitud

Ejemplo

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "user@example.com",
    "name": { "givenName": "Alex", "familyName": "Doe" },
    "emails": [{ "type": "work", "value": "user@example.com", "primary": true }],
    "active": true
  }' \
  "https://axe.deque.com/api/scim/v2/Users"

Respuesta 201 Created — el recurso de Usuario creado.

Errores

Reemplazar un usuario

PUT /api/scim/v2/Users/{id}

Actualiza el nombre y correo electrónico de un usuario.

Cuerpo de la solicitud

Respuesta 200 OK — el recurso de Usuario actualizado.

Errores

Activar o desactivar un usuario

PATCH /api/scim/v2/Users/{id}

Establece la membresía empresarial. active: true agrega al usuario a la empresa; active: false lo desprovisiona (remueve la membresía; se conserva la cuenta).

Cuerpo de la solicitud

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

Respuesta 204 No Content

Errores

Desprovisionar un usuario

DELETE /api/scim/v2/Users/{id}

Remueve al usuario de tu empresa (remoción suave — se conserva la cuenta).

Respuesta 204 No Content

Errores

Grupos

Los grupos son suscripciones de productos (otorgar un asiento de producto) o equipos (organizar usuarios). Ver Cómo SCIM funciona con la cuenta de axe.

Listar grupos

GET /api/scim/v2/Groups

Devuelve todas las suscripciones de productos y equipos para tu empresa. Este endpoint no se pagina.

Parámetros de consulta

Respuesta 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "startIndex": 1,
  "itemsPerPage": 5,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "grp-1",
      "displayName": "Axe Monitor",
      "members": [
        { "value": "5f3e...c2", "display": "user@example.com", "$ref": "/Users/5f3e...c2" }
      ]
    }
  ]
}

Obtener un grupo

GET /api/scim/v2/Groups/{id}

Respuesta 200 OK — un recurso de grupo.

Errores

Crear un grupo

POST /api/scim/v2/Groups

Crea un equipo. Si displayName coincide exactamente con el nombre de un producto para el que tu empresa tiene una suscripción activa, no se crea un equipo — en su lugar, se devuelve el grupo existente de suscripción al producto (201, con su id y Location), y cualquier members en el cuerpo de la solicitud son ignorados. Administra la membresía de ese grupo a través de PATCH /Groups/{id}.

La coincidencia distingue mayúsculas y minúsculas y es exacta. Si el nombre coincide con un producto cuya suscripción está no activa, se crea un equipo regular con ese nombre — no otorgará asientos de producto.

Cuerpo de la solicitud

Respuesta 201 Created — el recurso de Grupo creado, con un encabezado Location.

Errores

Actualizar membresía del grupo

PATCH /api/scim/v2/Groups/{id}

Agrega o elimina miembros. Para un grupo de suscripción, esto concede o revoca un asiento de producto. Para un grupo del equipo, esto cambia la membresía del equipo.

Cuerpo de la solicitud

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "add", "path": "members", "value": [ { "value": "5f3e...c2" } ] }
  ]
}

Usa op: "remove" con un path para eliminar miembros. Un replace con un array vacío elimina a todos los miembros.

Respuesta 204 No Content

Errores

Eliminar un grupo

DELETE /api/scim/v2/Groups/{id}

Elimina un equipo. Las solicitudes de eliminación contra un grupo de suscripción de productos son ignoradas (devuelve 204).

Respuesta 204 No Content

Errores

Actualizar un grupo (no soportado)

PUT /api/scim/v2/Groups/{id}

No soportado. Devuelve 405 Method not allowed. Usa PATCH para modificar la membresía.

Puntos de descubrimiento

Estos apoyan la configuración automática del conector. Todos devuelven 200 OK.

Relacionados

• Cómo SCIM trabaja con la cuenta axe
• Configuración de su proveedor de identidad
• Resolución de problemas