Skip to main content

Cosafe Support Center


Examples for sending SCIM requests

Important

This article provides examples of SCIM endpoint requests that the API supports. Your Identity Provider (IdP) typically handles these requests automatically, so manual interaction is usually unnecessary.

Use these examples only if you are building a custom connector and need to test against the SCIM API. Custom connectors can produce unstable or unpredictable results if they behave unexpectedly, so we generally discourage writing them from scratch. However, if your situation requires manual integration and you cannot use a pre-built third-party connector, refer to these examples for guidance.

Base URL​

Use the base URL provided during SCIM add-on activation. Examples in this document refer to this as <base-url>.

Headers​

All requests must include the following headers:

'Authorization': 'Bearer <your-api-key>',
'Content-Type': 'application/scim+json; charset=utf-8',

For simplicity, subsequent examples show only the URL and request body.

Limitations​

  • Maximum pagination count: 1000
  • Maximum members attribute length for requests: 1000
  • GET filter supports one attribute with the eq (equal) operation only

Read endpoints​

List all users​

GET <base-url>/Users

Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "userName": "john@example.com",
      "emails": [
        {
          "value": "john@example.com",
          "primary": true
        }
      ],
      "displayName": "John Doe",
      "phoneNumbers": [
        {
          "primary": true,
          "value": "+467017406351",
          "type": "work"
        },
        {
          "primary": false,
          "value": "+46313900642",
          "type": "mobile"
        }
      ]
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

List all groups​

GET <base-url>/Groups

Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "id": "8e9d1a59-bbe5-11f0-90fb-3e40deb6141c",
      "displayName": "West county -- all-staff"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Find existing user​

GET <base-url>/Users?filter=userName eq "john@example.com"

To check whether a user already exists in the system and to retrieve their id for subsequent requests, use the filter parameter with the matching attribute userName to find the user by their unique name.

If the user exists, the endpoint returns the user schema containing the id attribute, which you use for all subsequent requests for this user:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1,
  "Resources": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "userName": "john@example.com",
      "emails": [
        {
          "value": "john@example.com",
          "primary": true
        }
      ],
      "displayName": "John Doe",
      "phoneNumbers": [
        {
          "primary": true,
          "value": "+46701740635",
          "type": "work"
        },
        {
          "primary": false,
          "value": "+46313900642",
          "type": "mobile"
        }
      ]
    }
  ]
}

If the user does not exist, the endpoint returns 200 OK with an empty list.

Get a user​

Retrieve an existing user by making a GET request to the /Users endpoint with the user id.

GET <base-url>/Users/8693b7d1-afe8-11f0-8cc2-3a7cb373875a

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/8693b7d1-afe8-11f0-8cc2-3a7cb373875a"
  },
  "userName": "john@example.com",
  "displayName": "John Doe",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+46701740635",
      "type": "work"
    },
    {
      "primary": false,
      "value": "+46313900642",
      "type": "mobile"
    }
  ]
}

Use this endpoint to verify that the user still exists in the system or to check for mismatched attributes.

Find existing group​

Use the externalId attribute to find a group. For instructions on configuring the Group ID field in the Admin Panel, see Setting up groups.

GET <base-url>/Groups?filter=externalId eq "b55a6bbf-fcc1-4d06-943e-896d963b649a"

Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
      "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
      "displayName": "West county -- all-staff"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Important considerations:

  • If this endpoint returns "totalResults": 2 (or any value greater than 1), consider the association failed and do not attempt to use the first element of the list as the matched user.
  • If the group is not found, create a group from the Cosafe Admin Panel and set the Group ID as your internal system ID. This field becomes the externalId attribute.
  • The members attribute is excluded from this list. To retrieve members, use the get a group endpoint.
  • If the response does not contain the externalId attribute, the Group ID is not properly configured in the Admin Panel. See Setting up groups.

Get a group​

Retrieve an existing group by making a GET request to the /Groups endpoint with the group id.

GET <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- all-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" }
  ]
}

The members attribute contains a list of user IDs (id) belonging to that group as value.

In the group name, the prefix "West County" is not part of the group name. It is the name of the sub-account to which the group belongs. This prefix is appended for IdPs that need to distinguish returned groups by their displayName, as different sub-accounts often contain groups with identical names.

Create endpoints​

Create a user​

POST <base-url>/Users

Request body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "active": true,
  "userName": "john@example.com",
  "displayName": "John Doe",
  "title": "Teacher",
  "phoneNumbers": [
    { "primary": true, "type": "work", "value": "+46701740635" },
    { "primary": false, "type": "mobile", "value": "+46313900642" }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46313900642",
      "type": "mobile",
      "primary": false
    }
  ]
}

The response includes the id attribute, which you use for all subsequent requests for this user.

Create a group​

To create a group, create it in the Cosafe Admin Panel and set the Group ID as your internal system ID, which becomes the externalId.

Update endpoints​

The preferred method to modify a resource is to use a PATCH request with an operation on the attribute.

Update a group​

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "senior-staff"
    }
  ]
}

The PATCH operation request can contain multiple operations.

This request replaces "all-staff" with "senior-staff".

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" }
  ]
}

Update group members​

You can update group members using two approaches:

1. Partial update (add or remove specific users)​

Adding members:

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
        { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
      ]
    }
  ]
}

The element value is the user's id.

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Removing members:

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
        { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
      ]
    }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" }
  ]
}

2. Replace entire members array​

If you prefer to replace the entire members array, use a PUT request.

Note: This approach is not recommended for groups with a large number of members. For performance reasons, use partial updates via add/remove operations with only the changed memberships, including during initial group population.

PUT <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Request body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "displayName": "senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Update user plain attributes​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "John Doe Jr."
    }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46313900642",
      "type": "mobile",
      "primary": false
    }
  ]
}

Update user multi-valued attributes​

1. Replace phone numbers​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers",
      "value": [
        { "primary": true, "value": "+46701740635" },
        { "primary": false, "value": "+46406280473" }
      ]
    }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46406280473",
      "type": "mobile",
      "primary": false
    }
  ]
}

2. Replace phone numbers with removal​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers",
      "value": [{ "primary": true, "value": "+46701740635" }]
    }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "",
      "type": "mobile",
      "primary": false
    }
  ]
}

3. Entra-compatible format​

The API also supports the format sent by Entra:

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Request body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers[type eq \"mobile\"].value",
      "value": "+46980319247"
    }
  ]
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46980319247",
      "type": "mobile",
      "primary": false
    }
  ]
}

Delete endpoints​

Delete a user​

DELETE <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Response:

204 No Content

Subsequent GET requests for this resource by ID will return 404 Not Found.

Delete a group​

DELETE <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Response:

204 No Content

Subsequent GET requests for this resource by ID will return 404 Not Found.