SCIM Provisioning
The SCIM API is used by SCIM-enabled Identity Providers (IdPs) to automate provisioning and manage access for user accounts and teams (groups). The Mailosaur API is based on version 2.0 of the SCIM standard. The SCIM endpoint that an IdP should use is: https://mailosaur.com/api/scim/.
The SCIM API is only available to customers with an Enterprise plan, with Enterprise SSO enabled.
Authentication
To authenticate with the Mailosaur SCIM API, you must first create an account-level API key. As with all other authenticated calls to the Mailosaur API, this key must be passed using HTTP Basic Auth. Learn more about API authentication in our API reference.
SCIM user attributes
The following table maps SCIM attributes to the relevant fields that Mailosaur uses. Most of these profile fields are exposed directly in a person’s profile in the Mailosaur Dashboard:
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| displayName | string | The full name of the user. When provisioning a user, the name attributes are preferred to displayName. |
| name.givenName | string | The first name of the user. |
| name.familyName | string | The last name of the user. |
| emails | array | Whilst this is a list of user emails, Mailosaur only uses one, which will be associated with their Mailosaur account. If Mailosaur finds an email marked as primary (or one that is marked as the user’s “work” email address) then this will be used. Otherwise, the first email in the list will be selected. |
| userName | string | The email address associated with the Mailosaur user. May be used to set the email address for a user, if not set via the emails array. |
| id | string | Identifier generated by the Mailosaur SCIM endpoint. |
| externalId | string | This identifier is generated by the SAML provider, and is used as a unique ID by the SAML provider to match against a Mailosaur user. You can find the externalID for a user either at the SAML provider, or using the List SCIM provisioned identities endpoint and filtering on other known attributes, such as a user’s GitHub username or email address. |
| active | boolean | Indicates whether the identity is active (true) or should be deprovisioned (false). |
NOTE: Endpoint URLs for the SCIM API are case sensitive. For example, the first letter in the Users endpoint must be capitalized.
List users
Retrieves a paginated list of all users. If you provide the filter parameter, the resources for all matching provisioned users are returned.
Query parameters
- Name
startIndex- Type
integer- Description
- Used for pagination: the index of the first result to return.
- Name
count- Type
integer- Description
- Used for pagination: the number of results to return.
- Name
filter- Type
string- Description
- Filters results using the equals query parameter operator (eq). You can only filter results that are equal to the userName. For example, to search for an identity with the userName bob@yourdomain.com, you would use this query: ?filter=userName%20eq%20"bob@yourdomain.com".
GET https://mailosaur.com/api/scim/UsersProvision a user
Creates a new user. Must include the at least one email address. If an email address is marked as primary, it will be used.
This is an example request body for a typical provisioning request. In this example you@work.com will be used as it is marked as the primary email address (it would also have been used because it has the type work):
POST https://mailosaur.com/api/scim/Users{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0"
],
"name": {
"familyName": "Last",
"givenName": "First"
},
"displayName": "First Last",
"emails": [
{
"value": "you@work.com",
"type": "work",
"primary": true
},
{
"value": "you@home.com",
"type": "home"
}
],
"userType": "Employee",
"active": true
}Retrieve a user
Returns the attributes of an existing user.
GET https://mailosaur.com/api/scim/Users/{scim_user_id}Update a user
Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider.
PUT https://mailosaur.com/api/scim/Users/{scim_user_id}Delete a user
Deletes a user from your Mailosaur account
DELETE https://mailosaur.com/api/scim/Users/{scim_user_id}Groups (Teams)
SCIM groups are mapped to Mailosaur “Teams”, which can be used for organizing users in logical divisions across a workspace, such as by team or affinity.
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| displayName | string | The team (group) name. |
| members | array | Users that are assigned to this team (group). |
List groups
Returns a paginated list of groups.
GET https://mailosaur.com/api/scim/GroupsRetrieve a single group
Retrieves a single group resource.
GET https://mailosaur.com/api/scim/Groups/{scim_group_id}Create a group
Must include the displayName attribute (as defined in the schema specification). Users can be added to the group during creation by supplying their ID values in the members array attribute.
Here is an example of a typical request body for provisioning a new group:
POST https://mailosaur.com/api/scim/Groups{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "My New Team",
"members": [
{
"value": "fd98493c-c875-440f-be8f-7fbec0f50e43"
},
{
"value": "4f02f207-b90e-4b72-9ac4-6ea1c0368bc9"
}
]
}Update an existing group
Updates an existing group resource, overwriting all values for a group even if an attribute is empty or not provided. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider.
PUT https://mailosaur.com/api/scim/Groups/{scim_group_id}Delete a single SCIM group
Deletes an existing group from your Mailosaur account.
DELETE https://mailosaur.com/api/scim/Groups/{scim_group_id}