SCIM Examples

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

Summary

We currently support 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}
  • DELETE /{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://api.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]"
    }]
 }

GET /{id}

Retrieves a single user resource.

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

Example Request

curl --location --request GET 'https://api.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://api.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://api.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://api.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.

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"
        }
    ]
}

DELETE /{id}

Users can also be deactivated with the DELETE endpoint. Similar to updating the user’s active attribute to false, the user will no longer be able to sign in. However, their data will remain available as an inactive MURAL user.

Filtering responses

For the GET / Users method, it's possible to filter the list by the email and externalId attributes and return only the values matching that filter.

The externalId is used by your IdP to identify a resource (a user).

While the values of attributes (such as username) can be changed, or mappings can change, the value of a user’s externalId cannot be modified. Hence, filtering on externalId can be used to check whether users listed in your IdP also show in MURAL.

By default, our SCIM connectors map the externalId of users in MURAL to the IdP. In Okta, this value is "External ID" and in Azure AD it is "Object ID".

Service Provider Configuration

GET /ServiceProviderConfigs

Returns MURAL’s configuration details for our SCIM API, including which operations are supported.