Groups in SCIM API allow you to manage teams in your Miro Enterprise account. You can get the list of teams, add or remove team members and update team display name.

Group attributes

IDP attribute name

Miro attribute namespace

SCIM attribute

Description

Name

urn:ietf:params:scim:schemas:core:2.0:Group

displayName

Team's name. Mandatory field

Members

urn:ietf:params:scim:schemas:core:2.0:Group

members

List of team's members. Mandatory field.

Group methods

Get teams

GET: https://miro.com/api/v1/scim/Groups

Retrieves a list of groups (teams). Use startIndex and count query parameters to receive paginated results. Supports sorting and the filter parameter.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 2,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "3074457345620002842",
            "displayName": "Second team",
            "members": [
                {
                    "value": "3074457345619734493",
                    "type": "User"
                },
                {
                    "value": "3074457345619443315",
                    "type": "User"
                }
            ],
            "meta": {
                "resourceType": "Group",
                "location": "https://miro.com/api/v1/scim/Groups/3074457345620002842"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "3074457345619443317",
            "displayName": "First team",
            "members": [
                {
                    "value": "3074457345619783626",
                    "type": "User"
                },
                {
                    "value": "3074457345619577096",
                    "type": "User"
                },
                {
                    "value": "3074457345618870303",
                    "type": "User"
                },
                {
                    "value": "3074457345619734493",
                    "type": "User"
                },
                {
                    "value": "3074457345619443315",
                    "type": "User"
                },
                {
                    "value": "3074457345618796605",
                    "type": "User"
                }
            ],
            "meta": {
                "resourceType": "Group",
                "location": "https://miro.com/api/v1/scim/Groups/3074457345619443317"
            }
        }
    ]
}

Get team by ID

GET: https://miro.com/api/v1/scim/Groups/3074457345620002842

Retrieves a single Group resource.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "3074457345620002842",
    "meta": {
        "resourceType": "Group",
        "location": "https://miro.com/api/v1/scim/Groups/3074457345620002842"
    },
    "displayName": "Second team",
    "members": [
        {
            "value": "3074457345619734493",
            "type": "User"
        },
        {
            "value": "3074457345619443315",
            "type": "User"
        }
    ]
}

🚧

External users restrictions

Users with the role ORGANIZATION_EXTERNAL_USER or ORGANIZATION_TEAM_GUEST_USER are not retrieved for any account.

Update team by ID

PATCH: https://miro.com/api/v1/scim/Groups/3074457345620002842

Updates an existing group resource, overwriting values for specified attributes. Attributes that are not provided will remain unchanged. PATCH only updates the fields provided.

The body of a PATCH request must contain the attribute Operations, whose value is an array of one or more PATCH operations. Each PATCH operation object must have exactly one op member. To update a user resource, use replace operation.

The path attribute value is a String containing an attribute path describing the target of the operation. The path attribute is optional for add and replace and is required for remove operations.

This request will add 2 users and remove 1 user.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Add",
      "path": "members",
      "value": [
        {
          "value": "3074457345619783626"
        },
        {
          "value": "3074457345619577096"
        }
      ]
    },
    {
      "op": "Remove",
      "path": "members[value eq 3074457345619734493]"
    }
  ]
}
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "3074457345620002842",
    "meta": {
        "resourceType": "Group",
        "location": "https://miro.com/api/v1/scim/Groups/3074457345620002842"
    },
    "displayName": "Second team",
    "members": [
        {
            "value": "3074457345619783626",
            "type": "User"
        },
        {
            "value": "3074457345619577096",
            "type": "User"
        },
        {
            "value": "3074457345619443315",
            "type": "User"
        }
    ]
}

🚧

Team members removal restriction

The last team admin from the team cannot be removed. The API returns a 409 error code.

📘

Team members removal specifics

For remove or replace operations, the team member is removed from the team and from all team boards. If the user is not registered fully in Miro and is not assigned to any other team, the user is also removed from the organization.

📘

Add team members specifics

All added team members are reactivated or recreated if they were deactivated or deleted earlier.

📘

External users specifics

When adding existing users with the role ORGANIZATION_EXTERNAL_USER or ORGANIZATION_TEAM_GUEST_USER to a team, we set FULL license and ORGANIZATION_INTERNAL_USER roles.

❗️

Unsupported methods

Groups creation and deletion are not supported through SCIM, therefore POST and DELETE /Groups will return 405 error code.

Decoupling Groups and Teams

For enterprise companies that use identity providers to manage users and groups, it's very common to organize users into groups with cryptic names. Such group name makes most sense for company's internal administrators but makes less sense to be visible in Miro app. Security groups are designed to resolve this problem.
Imagine in IDP you have a group sfo_hq_eng_support. In Miro you can have a security group of the same name sfo_hq_eng_support which is mapped to a Miro Team Engineering Support.
At the moment there is a one-to-one mapping between security group and team. Changing the group's name through SCIM will in fact change the name of security group, not team. When the team in Miro is linked with a group in IDP the name of Security Group will be displayed on the Company teams view. You can also search teams by security group name.


Did this page help you?