SCIM Provisioning

Mailisk supports SCIM 2.0 so your identity provider can provision organisation users, manage their access and roles, and optionally synchronize groups and memberships.

SSO and SCIM are separate

SCIM manages access to the organisation and the roles of provisioned users. It does not authenticate users. Configure Single Sign-On separately if users should sign in through your identity provider.

Supported features

• Provision users
• Update supported user attributes and Mailisk roles
• Deactivate and reactivate users
• Optionally push groups and group memberships

Requirements

To configure SCIM, you need:

• A Mailisk organisation with the SSO plan enabled. An OIDC connection is optional.
• Mailisk organisation owner or admin access
• An identity provider that can provision users through SCIM 2.0

Create a SCIM connection

1. Open SSO settings in the Mailisk Dashboard.
2. Select the organisation that your identity provider should manage.
3. Under SCIM provisioning, click Generate token.
4. Copy the displayed SCIM base URL and bearer token.

The token is shown only once. Store it in your identity provider before closing the dialog.

Configure your identity provider with these values:

Setting	Value
SCIM or tenant URL	The complete SCIM base URL shown by Mailisk
Authentication	HTTP bearer token
Token	The generated sk_scim_... token

Mailisk uses the bearer token to identify the organisation. The SCIM base URL is the same for every organisation. Do not append /Users or /Groups unless your provider explicitly asks for a resource URL rather than a base URL.

Manual attribute mappings

Mailisk currently exposes the SCIM Users and Groups resources. If your provider does not have a built-in Mailisk integration, configure the user attributes below manually.

Mailisk expects the token in this header:

Authorization: Bearer sk_scim_YOUR_TOKEN

The Bearer scheme is required. Provider modes that send the token directly as Authorization: sk_scim_... are not currently supported.

Before the first sync, enable Send access instructions to new SCIM users if Mailisk should email people who do not yet have an account. Only users provisioned or reactivated after this setting is enabled receive an email.

Enable Create users, Update user attributes, and Deactivate users when your provider exposes those options. Test the connection, assign the users that should be provisioned, and confirm that user provisioning succeeds. Then enable Push groups if you want groups and memberships mirrored in Mailisk.

User attributes

The following attributes control Mailisk user provisioning:

SCIM attribute	Required	Description
userName	Yes	The identity provider's case-insensitive identifier for the user. It does not need to be an email address.
emails	Yes	Contains the email address of the Mailisk account.
active	No	Controls access to the organisation. New users default to active.
roles	No	Sets the Mailisk organisation role to USER or ADMIN.
externalId	No	Stable identifier generated by the identity provider.
id	Response only	Stable identifier generated by Mailisk for the provisioned resource.

Account email

Mailisk requires one unambiguous account email. Send a single address marked as primary when possible:

{
  "userName": "alex",
  "emails": [
    {
      "value": "alex@example.com",
      "primary": true
    }
  ]
}

userName does not need to be an email address. The account email cannot be changed through SCIM after provisioning.

Users who have not signed up yet

If SCIM provisions someone without a verified Mailisk account, their access remains pending until their Mailisk account email is verified.

Mailisk does not email them by default. Deactivated pending users do not receive organisation access until the identity provider reactivates them.

Roles

Mailisk supports two SCIM-managed organisation roles:

• USER
• ADMIN

Map the provider's role value to the standard SCIM roles[].value attribute. Send exactly one value:

{
  "roles": [
    {
      "value": "ADMIN"
    }
  ]
}

The role value can be USER or ADMIN. When one role is sent, type, display, and primary are optional. If the provider requires a type to select an entry in the complex roles attribute, use mailiskRole.

Do not create a separate custom role attribute. Mailisk accepts roles only through the standard SCIM roles attribute.

If no role is supplied, Mailisk preserves an existing USER or ADMIN membership for an adopted account. Otherwise, it assigns USER. Later updates that omit the role preserve the current role.

Organisation owners cannot be managed through SCIM. Transfer ownership or use another account before provisioning an existing owner.

SCIM-managed roles

Change the role of a SCIM-managed user in the identity provider. Mailisk prevents direct role changes for these users so that the two systems do not become inconsistent.

Groups

Group Push is optional. Enable it only when you want groups and memberships mirrored in Mailisk.

Group Push does not provision users. Each group member must first be assigned to the SCIM application and successfully provisioned as a User resource. If a member has not been provisioned, the identity provider may omit them from the pushed group or create the group with an empty membership list.

Pushed groups do not assign roles or grant organisation access. Send USER or ADMIN on each SCIM User resource to manage permissions.

Validate the connection

You can test the base URL and token without modifying a user:

curl --fail-with-body \
  --header "Authorization: Bearer $MAILISK_SCIM_TOKEN" \
  --header "Accept: application/scim+json" \
  "$MAILISK_SCIM_BASE_URL/Users?count=1"

A working connection returns 200 with a SCIM ListResponse. The Last used value in Mailisk confirms that an authenticated request reached the API. It does not prove that a later provisioning operation succeeded.

Existing Mailisk users

When the selected SCIM email matches an existing verified Mailisk account, Mailisk uses that account instead of creating a duplicate. An existing unverified account remains pending until its owner verifies the email. SCIM does not change how existing users sign in. Password and social login remain available unless SSO domain enforcement requires them to use SSO.

Deactivation removes access only to the managed organisation. It does not delete the global Mailisk account or memberships in other organisations. Reactivation restores the managed organisation membership and role.

Rotate a token

Organisation owners and admins can rotate the token from SCIM provisioning in the Mailisk SSO settings.

Rotation invalidates the previous token immediately. Copy the replacement token into your identity provider before running another sync. The Dashboard shows when the active token was created and when it was last used.

Troubleshooting

The token has not been used

If the Dashboard says that the token has not been used, it usually means the identity provider has not successfully authenticated to the displayed SCIM base URL. Check the URL, bearer token, network access, and whether a connection test or sync was started.

Common API errors include:

Status	Meaning
401	The token is missing, invalid, or has been rotated.
403	SCIM is unavailable for the organisation, or the matching Mailisk account is disabled.
400 with mutability	The provider tried to manage an organisation owner or change the account email.

A user is not provisioned

Check that:

• The user is included in the provider's provisioning scope
• The provider sends one unambiguous account email in emails
• The email identifies the expected Mailisk account
• The target account is not the organisation owner
• The provider's sync or provisioning logs do not contain a SCIM error response

A role is not updated

Check that:

• The provider sends roles on the User resource, not only group membership
• The value is USER or ADMIN
• The provider maps its role source to roles[].value
• No separate custom role attribute is configured
• The role mapping is enabled in the provider's user provisioning configuration
• A full user sync ran after the mapping or source attribute changed