SCIM Examples

This article explains the available SCIM endpoints and provides examples on how to use them.

Summary

As part of the first milestone, we have implemented SCIM user endpoints.

SCIM users map to members within a MURAL company or workspace. Each member contains properties called attributes, like givenName, lastName and email.

With SCIM, you can list all members in your company, create a new member, update a member’s profile information, or suspend a member.

Here are the currently supported endpoints:

  • GET /Users
  • GET /Users/{id}
  • POST /Users
  • PUT /Users/{id}
  • PATCH /Users/{id}

User methods

GET

Returns a list of members.

For this first release, we support filtering by a user’s email. Pagination, list sorting, and other filters are not currently supported.

Example request

curl --location --request GET 'https://app.mural.co/enterprise/v1/scim/Users/' \

--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'

Example response

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [ {
       "active":true,
       "emails":[
          {
             "primary":true,
             "value":"[email protected]"
          }
       ],
       "id":"udf4297df66b9aa4b6a856182",
       "meta":{
          "created":"2020-06-23T18:59:57.913Z",
          "lastModified":"2021-05-26T15:22:51.022Z",
          "resourceType":"User"
       },
       "name":{
          "familyName":"Maximoff",
          "givenName":"Wanda"
       },
       "schemas":[
          "urn:ietf:params:scim:schemas:core:2.0:User"
       ],
       "userName":"[email protected]"
    }]
 }

Filter by email using GET

Example Request

curl --location --request GET 'https://app.mural.co/enterprise/v1/scim/Users?filter=userName%20eq%20%[email protected]%22' \
--header 'Authorization: apiKey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi' \

Example Response

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "startIndex": 1,
   "itemsPerPage": 1,
   "Resources": [ {
      "active":true,
      "emails":[
         {
            "primary":true,
            "value":"[email protected]"
         }
      ],
      "id":"udf658a6b4aa9b66fd7924182",
      "meta":{
         "created":"2020-06-23T18:59:57.913Z",
         "lastModified":"2021-05-26T15:22:51.022Z",
         "resourceType":"User"
      },
      "name":{
         "familyName":"Parker",
         "givenName":"Peter"
      },
      "schemas":[
         "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "userName":"[email protected]"
   }]
}

GET /{id}

Retrieves a single user resource.

The {id} value is the user’s corresponding MURAL ID.

Example Request

curl --location --request GET 'https://app.mural.co/enterprise/v1/scim/Users/udf658a6b4aa9b66fd7924182' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'

Example Response

   {
      "active":true,
      "emails":[
         {
            "primary":true,
            "value":"[email protected]"
         }
      ],
      "id":"udf658a6b4aa9b66fd7924182",
      "meta":{
         "created":"2020-06-23T18:59:57.913Z",
         "lastModified":"2021-05-26T15:22:51.022Z",
         "resourceType":"User"
      },
      "name":{
         "familyName":"Banner",
         "givenName":"Bruce"
      },
      "schemas":[
         "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "userName":"[email protected]"
   }

POST

Creates a user.

A user must include a username (email), given (first) name, and family (last) name.

Example request

curl --location --request POST 'https://app.mural.co/enterprise/v1/scim/Users/ \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'
--header 'Content-Type: application/scim+json' \
--data-raw ' {
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User"
   ],
   "userName":"[email protected]",
   "name":{
      "familyName":"Pym",
      "givenName":"Henry"
   }
}'

Example response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "id": "udf4297df66b9aa4b6a856182",
    "meta": {
        "created": "2020-06-23T18:59:57.913Z",
        "lastModified": "2021-05-26T15:22:51.022Z",
        "resourceType": "User"
    },
    "name": {
        "familyName": "Pym",
        "givenName": "Henry"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "[email protected]"
}

PUT /{id}

Updates an existing user resource, overwriting all values for a user, even if an attribute is empty or not provided.

Example request

curl --location --request PUT 'https://app.mural.co/enterprise/v1/scim/Users/udf4297df66b9aa4b6a856182 \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'
--header 'Content-Type: application/json' \
--data-raw ' {
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User"
   ],
   "active": true,
   "userName":"[email protected]",
   "name":{
      "familyName":"Natasha",
      "givenName":"Romanov"
   }
}’

Example response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "id": "udf4297df66b9aa4b6a856182",
    "meta": {
        "created": "2020-06-23T18:59:57.913Z",
        "lastModified": "2021-05-26T15:22:51.022Z",
        "resourceType": "User"
    },
    "name": {
        "familyName": "Natasha",
        "givenName": "Romanov"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "[email protected]"
}

PATCH /{id}

Updates an existing user resource, overwriting values for specific attributes.

Attributes that are not provided in the request are not changed. The {id} value is the user’s corresponding MURAL ID.

Example request

curl --location --request PATCH 'https://app.mural.co/enterprise/v1/scim/Users/udf4297df66b9aa4b6a856182 \
--header 'Authorization: apikey ZTcO2UWYyQzMkVGOtIGOlFWLycjY00SM0QWNtcDO4YDM2UWN.00M.zIDOkV2MmRWZzMGMtMzM4IWLjRmZ00SO2gzMtUmMlNzN5TA3' \
--header 'Content-Type: application/json' \
--data-raw ' {
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
      ],
      "Operations" : [
        {
          "op":"replace",
          "path":"userName",
          "value": "[email protected]"
        }
      ]
  }'

Example response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "id": "udf4297df66b9aa4b6a856182",
    "meta": {
        "created": "2020-06-23T18:59:57.913Z",
        "lastModified": "2021-05-26T15:22:51.022Z",
        "resourceType": "User"
    },
    "name": {
        "familyName": "Donald",
        "givenName": "Blake"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "[email protected]"
}

PATCH: Deactivate active users


Deactivate active users by setting the active attribute to false.

In this instance, the user will no longer be able to sign in. However, their data will remain available as an inactive MURAL user.

This first release of SCIM doesn't support permanent deletion of users through a DELETE endpoint.

To reactivate previously deactivated users, set the active attribute to true.

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

PATCH: Update a user's email (username)

Update the user's username (email) by setting the userName attribute to their new email address.

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

PATCH: Update a user's given name (first name)

Update the user's given name by setting the name.givenName attribute to the new given name of the user.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "path": "name.givenName",
            "value": "Jenny"
        }
    ]
}

PATCH: Update a user's family name (last name)

Update the user's family name by setting the name.familyName attribute to the new family name of the user.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "path": "name.familyName",
            "value": "Rodriguez"
        }
    ]
}

Did this page help you?