Mailosaur

SCIM

Manage the access granted to your users using the SCIM API.

Applies to:

Enterprise plans

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:

NameTypeDescription
displayNamestringThe full name of the user. When provisioning a user, the name attributes are preferred to displayName.
name.givenNamestringThe first name of the user.
name.familyNamestringThe last name of the user.
emailsarrayWhilst 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.
userNamestringThe 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.
idstringIdentifier generated by the Mailosaur SCIM endpoint.
externalIdstringThis 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.
activebooleanIndicates 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.

get https://mailosaur.com/api/scim/Users

Parameters

NameTypeInDescription
startIndexintegerqueryUsed for pagination: the index of the first result to return.
countintegerqueryUsed for pagination: the number of results to return.
filterstringqueryFilters 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".

Provision 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.

post https://mailosaur.com/api/scim/Users

Request

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
}

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 Mailosaur

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.

NameTypeDescription
displayNamestringThe team (group) name.
membersarrayUsers that are assigned to this team (group).

List groups

Returns a paginated list of groups.

get https://mailosaur.com/api/scim/Groups

Retrieve 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.

post https://mailosaur.com/api/scim/Groups

Request

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"
        }
    ]
}

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.

delete https://mailosaur.com/api/scim/Groups/{scim_group_id}