SCIM Provisioning![A hashtag icon]()
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![A hashtag icon]()
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![A hashtag icon]()
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.
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".
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):
{
"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
}
Returns the attributes of an existing 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.
Groups (Teams)![A hashtag icon]()
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). |
Retrieves a single group resource.
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:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "My New Team",
"members": [
{
"value": "fd98493c-c875-440f-be8f-7fbec0f50e43"
},
{
"value": "4f02f207-b90e-4b72-9ac4-6ea1c0368bc9"
}
]
}
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.
Deletes an existing group.