Groups
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.
The ownership of boards that belong to the removed team member is transferred to the oldest team member who currently has an admin role. After you remove a team member, adding the team member again to the team does not automatically restore their previous ownership of the 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 that in an 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.
Updated about 1 year ago