Users
With SCIM API you can manage users in your Enterprise account. You can get the full list of users, filter by attribute, add new users, update user's attributes, activate or deactivate users and delete users completely.
User attributes
The following table lists the user attributes we support. Scroll to the right to see the description.
| IDP attribute name | Miro attribute namespace | Miro attribute | Description |
|---|---|---|---|
| urn:ietf:params:scim:schemas:core:2.0:User | userName | User email. Mandatory field. | |
| Full name | urn:ietf:params:scim:schemas:core:2.0:User | displayName | Attribute is used if the value is not empty. Maximum length: 60 characters. |
| urn:ietf:params:scim:schemas:core:2.0:User | name.formatted | Attribute is used if the displayName attribute is not provided, name attribute is provided and 'formatted' attribute value is not empty.Maximum length: 60 characters. | |
| urn:ietf:params:scim:schemas:core:2.0:User | name.givenName + " " + name.familyName | Attributes are used if the displayName attribute is not provided, name attribute is provided and formatted attribute is not provided.Maximum length: Combined character count for both fields must not exceed 60 characters. | |
| urn:ietf:params:scim:schemas:core:2.0:User | userName | Attribute will be used as full name if the displayName attribute is not provided and name attribute is not provided. | |
| User type | urn:ietf:params:scim:schemas:core:2.0:User | userType | Supported value: FullWhen userType=Full, a user is upgraded to FULL license inside the Miro application. When userType is not specified, user license is updated/set according to internal Miro logic, which depends on the organization plan. |
| Active | urn:ietf:params:scim:schemas:core:2.0:User | active | Supported value: true or false |
| Profile picture | urn:ietf:params:scim:schemas:core:2.0:User | photos.^[type=='photo'].value or photos.^[type==photo].value (Okta)photos[type eq "photo"].value (Azure) | Must be a text URL to the image. Supported file types: jpg, jpeg, bmp, png, gif To define file type, you should have defined file extension in url (e.g. https://host.com/avatar_user1.jpg) or request to url should return together with a file content a header Content-Type (e.g. Content-Type = 'image/jpeg') Max file size to download is: 31457280 bytes |
| Role | urn:ietf:params:scim:schemas:core:2.0:User | roles.^[primary==true].value (Okta)roles[primary eq "True"].value (Azure) | Supported values are:ORGANIZATION_INTERNAL_ADMINORGANIZATION_INTERNAL_USER |
Miro attribute namespace
'urn:ietf:params:scim:schemas:core:2.0:User' is a default SCIM urn for basic fields. If your identity provider does not require defining namespace, the default namespace must be avoided.
The following table lists the Enterprise user extensions attributes we support. Scroll to the right to see the description.
| IDP attribute name | Miro attribute namespace (urn) | Miro attribute | Description |
|---|---|---|---|
| Employee number | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | employeeNumber | Maximum length: 20 characters. |
| Cost center | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | costCenter | Maximum length: 120 characters. |
| Organization | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | organization | Maximum length: 120 characters. |
| Division | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | division | Maximum length: 120 characters. |
| Department | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | department | Maximum length: 120 characters. |
| Manager name | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | manager.displayName | Maximum length: 60 characters. |
| Manager id | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | manager.value | The "value" field has String type in SCIM standard but the managerId internal Miro field has Long type. If the "value" attribute is not a numeric value, we ignore the value. |
SCIM variables
The SCIM variable must have the following structure: ':.'.
Example: 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.displayName'
User methods
Get users
GET: https://miro.com/api/v1/scim/Users
Retrieves the list of users in your organization. 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:User"
],
"id": "3074457345619443315",
"userName": "[email protected]",
"name": {
"familyName": "",
"givenName": "Maxim"
},
"displayName": "Max",
"active": true,
"userType": "Full",
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
],
"groups": [
{
"value": "3074457345620002842",
"display": "Second team"
},
{
"value": "3074457345619443317",
"display": "First team"
}
],
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345619443315"
}
},
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "3074457345619734493",
"userName": "[email protected]",
"name": {
"familyName": "",
"givenName": "[email protected]"
},
"displayName": "[email protected]",
"active": true,
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
],
"groups": [
{
"value": "3074457345620002842",
"display": "Second team"
},
{
"value": "3074457345619443317",
"display": "First team"
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
"employeeNumber" : "701984",
"organization" : "Universal Studios",
"costCenter" : "4130",
"division" : "Theme Park",
"department" : "Tour Operations",
"manager" : {
"displayName" : "John Smith",
"value" : "32235455623567"
}
},
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345619734493"
}
}
]
}
Sorting
Sorting allows you to specify the order in which resources are returned by specifying a combination of sortBy and sortOrder URL parameters.
The sortBy parameter specifies the attribute whose value will be used to order the returned responses. The sortOrder parameter defines the order in which the sortBy parameter is applied. Allowed values are ascending and descending.
Filters
You can request a subset of resources by specifying the filter query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.
eq equal
ne not equal
co contains
sw starts with
ew ends with
pr preset (has value)
gt greater than
ge greater than or equal to
lt less than
le less than or equal to
and Logical "and"
or Logical "or"
not "Not" function
() Precedence grouping
NOTES: Miro only stores the full name of our users. For compatibility reasons, we use a combination of givenName and familyName if the displayName attribute is not present in a request. We also attempt to include a derived givenName and familyName in responses for users. However, you must not rely on this as filtering by name.givenName and name.familyName might not give the expected results. Consider using co, sw and similar operations to achieve what you need.
External users restrictions
Users with role ORGANIZATION_EXTERNAL_USER or ORGANIZATION_TEAM_GUEST_USER are not retrieved in this request.
Example of complex request:
GET: https://miro.com/api/v1/scim/Users?attributes=name,userName&filter=NOT(name.familyName eq "Green")&sortBy=name.givenName&sortOrder=ascending&startIndex=2&count=5
Get user by ID
GET: https://miro.com/api/v1/scim/Users/3074457345619443315
Retrieves a single user resource
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "3074457345619443315",
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345619443315"
},
"userName": "[email protected]",
"name": {
"familyName": "Oleg",
"givenName": "Test"
},
"displayName": "Oleg",
"active": true,
"userType": "Full",
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
"employeeNumber" : "701984",
"costCenter" : "4130",
"organization" : "Universal Studios",
"division" : "Theme Park",
"department" : "Tour Operations",
"manager" : {
"displayName" : "John Smith",
"value" : "32235455623567"
}
},
"photos": [
{
"type": "photo",
"value": "https://example.com/example.jpg"
}
],
"groups": [
{
"value": "3074457345620002842",
"display": "Second team"
},
{
"value": "3074457345619443317",
"display": "First team"
}
],
"roles": [
{
"value": "ORGANIZATION_INTERNAL_ADMIN",
"display": "Company Admin",
"type": "organization_user_role",
"primary": true
}
]
}
External users restrictions
Users with the role ORGANIZATION_EXTERNAL_USER or ORGANIZATION_TEAM_GUEST_USER are not retrieved. The API returns a 404 error code.
Create a new user
POST: https://miro.com/api/v1/scim/Users
Creates a new user. Payload must include userName attribute populated with an email address, familyName, and givenName or a displayName attribute. If displayName is not populated, a combination of givenName and familyName is used.
All newly provisioned users are added to the default team.
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"[email protected]",
"name":{
"familyName":"test family",
"givenName":"test given"
}
}
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "3074457345620139606",
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345620139606"
},
"userName": "[email protected]",
"name": {
"familyName": "given test family",
"givenName": "test"
},
"displayName": "test given test family",
"active": true,
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
]
}
Replace user by ID
PUT: https://miro.com/api/v1/scim/Users/3074457345620139606
Updates an existing user resource. This is the easiest way to replace the user information.
If the user is deactivated:
- The following parameters cannot be updated and will return an error:
userNameuserTyperoles.value
- The following fields will be ignored and will not return any errors:
emails.valueemails.displayemails.primary
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "3074457345619443315",
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345619443315"
},
"userName": "[email protected]",
"name": {
"familyName": "Oleg",
"givenName": "Test"
},
"displayName": "Oleg",
"active": true,
"userType": "Full",
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
"employeeNumber" : "701984",
"costCenter" : "4130",
"organization" : "Universal Studios",
"division" : "Theme Park",
"department" : "Tour Operations",
"manager" : {
"displayName" : "John Smith",
"value" : "32235455623567"
}
},
"photos": [
{
"type": "photo",
"value": "https://example.com/example.jpg"
}
],
"groups": [
{
"value": "3074457345619443317",
"display": "First team"
}
],
"roles": [
{
"value": "ORGANIZATION_INTERNAL_ADMIN",
"primary": true
}
]
}
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "3074457345619443315",
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345619443315"
},
"userName": "[email protected]",
"name": {
"familyName": "Oleg",
"givenName": "Test"
},
"displayName": "Oleg",
"active": true,
"userType": "Full",
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
"employeeNumber" : "701984",
"costCenter" : "4130",
"division" : "Theme Park",
"organization" : "Universal Studios",
"department" : "Tour Operations",
"manager" : {
"displayName" : "John Smith",
"value" : "32235455623567"
}
},
"photos": [
{
"type": "photo"
"value": "https://example.com/example.jpg"
}
],
"groups": [
{
"value": "3074457345619443317",
"display": "First team"
}
],
"roles": [
{
"value": "ORGANIZATION_INTERNAL_ADMIN",
"display": "Company Admin",
"type": "organization_user_role",
"primary": true
}
]
}
Update user attribute by ID
PATCH: https://miro.com/api/v1/scim/Users/3074457345619443315
Updates an existing user 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.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
]
}
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "displayName",
"value": "New displayName"
}
]
}
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "userType",
"value": "Full"
}
]
}
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
"value": "IT"
}
]
}
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "userName",
"value": "[email protected]"
}
]
}
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "roles.value",
"value": "ORGANIZATION_INTERNAL_ADMIN"
}
]
}
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "3074457345619443315",
"meta": {
"resourceType": "User",
"location": "https://miro.com/api/v1/scim/Users/3074457345619443315"
},
"userName": "[email protected]",
"name": {
"familyName": "displayName",
"givenName": "New"
},
"displayName": "New displayName",
"active": true,
"userType": "Full",
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true
}
],
"groups": [
{
"value": "3074457345620002842",
"display": "Second team"
},
{
"value": "3074457345619443317",
"display": "First team"
}
],
"roles": [
{
"value": "ORGANIZATION_INTERNAL_ADMIN",
"display": "Company Admin",
"type": "organization_user_role",
"primary": true
}
]
}
External users restrictions
Users with the role ORGANIZATION_EXTERNAL_USER or ORGANIZATION_TEAM_GUEST_USER cannot be updated. The API returns a 404 error code.
Delete user by ID
DELETE: https://miro.com/api/v1/scim/Users/3074457345620139606
Deletes a single user from the organization.
User removing restrictions
A user who is the last admin in the team or the last admin in the organization cannot be deleted. If you try to delete such user, the API returns a 409 error code.
External users restrictions
Users with the role ORGANIZATION_EXTERNAL_USER or ORGANIZATION_TEAM_GUEST_USER cannot be deleted. The API returns a 404 error code.
User content ownership transfer
After a user is deleted, the ownership of all the boards that belong to the deleted user is transferred to the oldest team member who currently has an admin role.
The response body is empty.
Updated 10 months ago