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

Summary

We currently support SCIM user and group provisioning.

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.

SCIM groups map to Mural workspaces. With our SCIM group endpoints, you can list all groups in your company, add a member to a group, remove a member from a group, replace members in a group, update a group name, or delete a group.

Here are the currently supported endpoints:

GET /Users
GET /Users/{id}
POST /Users
PUT /Users/{id}
PATCH /Users/{id}
DELETE /{id}
GET /Groups
GET /Groups/{groupId}
POST /Groups
PATCH /Groups/{groupId}
DELETE /Groups/{groupId}

User methods

GET

Returns a list of members.

For this first release, we support filtering by a user’s email. 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}

Performs a true delete operation, erasing all user identity data in Mural and preventing reactivation.

Note: For a soft delete enabling user reactivation, use a PATCH call to set 'active' == ‘false’.

SCIM Group methods

Use the SCIM API to create, update, and retrieve groups.

GET

Returns a list of all groups.

📘
When performing this GET call, the maximum number of results per page is 100. To view more results, you can paginate the call response using the count parameter. For example, to retrieve the first 100 users, the count parameter would be ?count=100&startIndex=1. Then to view the next 100, the parameter would be ?count=100&startIndex=101.

Example request

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

Example response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "id": "dedda5d6-6280-4d94-a523-d3084a22734e",
      "externalId": "37d79dfc86379e8db56bd124f43e3baa82ca057a",
      "meta": {
        "created": "2023-03-31T13:00:00.000Z",
        "lastModified": "2023-03-31T13:00:00.000Z",
        "resourceType": "Group"
      },
      "members": [
        {
          "value": "udf4297df66b9aa4b6a856182"
        },
        {
          "value": "udf658a6b4aa9b66fd7924182"
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "displayName":"Product Engineers"
    },
    {
      "id": "b9e01a94-b292-47e4-90a4-8375528a93b6",
      "externalId": "be37e0fe49d9e3bfb5348dbaaab3bf94c2d1d11d",
      "meta": {
        "created": "2023-03-31T13:00:00.000Z",
        "lastModified": "2023-03-31T13:00:00.000Z",
        "resourceType": "Group"
      },
      "members": [
        {
          "value": "udf4297df66b9aa4b6a856182"
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "displayName":"Sales Engineers"
    }
  ]
}

GET /{id}

Retrieves a single group resource.

The {id} value is the group’s corresponding Mural Group ID.

Example Request

curl --location --request GET 'https://api.mural.co/enterprise/v1/mapping/groups/dedda5d6-6280-4d94-a523-d3084a22734e' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'

Example Response


{
  "id": "dedda5d6-6280-4d94-a523-d3084a22734e",
  "externalId": "37d79dfc86379e8db56bd124f43e3baa82ca057a",
  "meta": {
    "created": "2023-03-31T13:00:00.000Z",
    "lastModified": "2023-03-31T13:00:00.000Z",
    "resourceType": "Group"
  },
  "members":[
    {
      "value": "udf4297df66b9aa4b6a856182"
    },
    {
      "value": "udf658a6b4aa9b66fd7924182"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName":"Product Engineers"
}

POST

Creates a group.

A group must include a displayName and the user IDs of the members that should be part of this group.

Example request

curl --location --request POST 'https://api.mural.co/enterprise/v1/scim/Groups' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi' \
--header 'Content-Type: application/scim+json' \
--data-raw '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Product Engineers", "externalId": "37d79dfc86379e8db56bd124f43e3baa82ca057a", "members": [] }'

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Product Engineers",
  "externalId": "37d79dfc86379e8db56bd124f43e3baa82ca057a",
  "members": [
    { "value": "udf4297df66b9aa4b6a856182" },
    { "value": "udf658a6b4aa9b66fd7924182" }
  ]
}

Example response


{
  "id": "dedda5d6-6280-4d94-a523-d3084a22734e",
  "externalId": "37d79dfc86379e8db56bd124f43e3baa82ca057a",
  "meta": {
    "created": "2023-03-31T13:00:00.000Z",
    "lastModified": "2023-03-31T13:00:00.000Z",
    "resourceType": "Group"
  },
  "members":[
    {
      "value": "udf4297df66b9aa4b6a856182"
    },
    {
      "value": "udf658a6b4aa9b66fd7924182"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName":"Product Engineers"
}

PATCH /{id}

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

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

PATCH: Add group members

Add member(s) to a group. This member will now have access to the mapped workspaces of the group.

Example request

curl --location --request PATCH 'https://api.mural.co/enterprise/v1/scim/Groups/37d79dfc86379e8db56bd124f43e3baa82ca057a' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi' \
--header 'Content-Type: application/scim+json' \
--data-raw '{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations" : [ { "op":"replace", "path":"displayName", "value": "New Group Name" } ] }'

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "udf4297df66b9aa4b6a856182" },
        { "value": "udf658a6b4aa9b66fd7924182" }
      ]
    }
  ]
}

PATCH: Remove group members

Remove member(s) from a group.

When you remove a member from a group, their access to the mapped workspaces of that group is revoked. This doesn't fully deactivate the member. And if the member is part of another active group, they will still have access to Mural.

Example request

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        { "value": "udf4297df66b9aa4b6a856182" },
        { "value": "udf658a6b4aa9b66fd7924182" }
      ]
    }
  ]
}

PATCH: Replace group members

Update the members of a group. This overwrites existing group memberships.

Example request

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "members",
      "value": [
        { "value": "udf4297df66b9aa4b6a856182" },
        { "value": "udf658a6b4aa9b66fd7924182" }
      ]
    }
  ]
}

DELETE /{id}

You can deactivate a group and revoke access to its corresponding workspace by using the DELETE endpoint. Once a group is deactivated, its members will no longer be able to access the workspace through the group mapping.

Example request

curl --location --request DELETE 'https://api.mural.co/enterprise/v1/scim/Groups/37d79dfc86379e8db56bd124f43e3baa82ca057a' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'

📘
If a member is a member of two groups that are mapped to the same workspace and only one of those groups is deleted, the member will still be able to access the workspace through the remaining active group.

Mapping methods

Use Mural’s mapping API to map groups to Mural workspaces and set group permissions.

GET

Returns a list of all group workspace mappings.

Example request

curl --location --request GET 'https://api.mural.co/enterprise/v1/mapping/groups' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'

Example response

{
  "Resources": [
    {
      "id": "dedda5d6-6280-4d94-a523-d3084a22734e",
      "name": "Product Engineers",
      "workspaces": {
        "companyworkspace1234": ["createRooms", "canDiscoverPublicRooms", "canPublishTemplates", "admin"],
        "companyworkspace5678": ["canPublishTemplates"]
      }
    },
    {
      "id": "b9e01a94-b292-47e4-90a4-8375528a93b6",
      "name": "Sales Engineers",
      "workspaces": {
        "companyworkspace1234": ["createRooms"],
        "companyworkspace5678": []
      }
    }
  ],
  "totalResults": 2,
  "startIndex": 1,
  "itemsPerPage": 20
}

GET /{id}

Retrieves a single group workspace mapping.

The {id} value is the group’s corresponding Mural Group ID.

Example request

curl --location --request GET 'https://api.mural.co/enterprise/v1/mapping/groups/dedda5d6-6280-4d94-a523-d3084a22734e' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi'

Example response

{
  "id": "dedda5d6-6280-4d94-a523-d3084a22734e",
  "name": "Product Engineers",
  "workspaces": {
    "companyworkspace1234": ["createRooms", "canDiscoverPublicRooms", "canPublishTemplates", "admin"],
    "companyworkspace5678": ["canPublishTemplates"]
  }
}

PATCH /{id}

Updates an existing group workspace mapping and/or group permission set.

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

PATCH: Add workspaces to group and set permissions

Use this endpoint to add workspaces to a group and set permissions. Members in the group will gain access to the mapped workspace(s) with the assigned permissions. You can find the Workspace ID in Mural's Workspaces page of the company dashboard, through Mural's Workspace Reporting API, or by downloading the Workspaces report from the company dashboard.

📘
If the admin permission is set to true, all other permissions must also be true.

Example request

curl --location --request PATCH 'https://api.mural.co/enterprise/v1/mapping/groups/dedda5d6-6280-4d94-a523-d3084a22734e' \
--header 'Authorization: apikey NjlZxMWN0ADM3ImZtQTZhhTL5QGZ00iZ0MmMtI2MkRDO4MzN.vN3ctwWYuJXZ05Wa.iVmM4QWN1UWZjFDZtIWOmhTLmRTZ00iNhJjMtkTN0MGOkDNi' \
--header 'Content-Type: application/json' \
--data-raw '{ "action": "add", "workspaceIds": [ "companyworkspace1234", "companyworkspace5678" ], "permissions": { "createRooms": true, "canPublishTemplates": true, "canDiscoverPublicRooms": false, "admin": false } }'

{
  "action": "add",
  "workspaceIds": [
    "companyworkspace1234",
    "companyworkspace5678"
  ],
  "permissions": {
    "createRooms": true,
    "canPublishTemplates": true,
    "canDiscoverPublicRooms": false,
    "admin": false

  }
}

Example response

{
  "name": "Product Engineers"
}

PATCH: Remove workspaces from group

Use this endpoint to remove a group workspace mapping. Members in the group will no longer have access to this workspace through the group mapping.

📘
If workspace sharing is enabled, members can still access the workspace outside of group membership. Managing their workspace membership needs to be done in the Mural UI. To prevent members from joining workspaces outside of their assigned group, disable workspace sharing by setting invite permissions to No new members and guests.

Example request

{
  "action": "remove",
  "workspaceIds": [
    "companyworkspace1234",
    "companyworkspace5678"
  ]
}

Example response

{
  "name": "Product Engineers"
}

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.