# SCIM provisioning

Use SCIM 2.0 to create, update, deactivate, and group organization users from your identity provider. MailSlurp exposes an organization-specific SCIM tenant URL and bearer token so your IdP can own the user lifecycle while MailSlurp keeps inbox, phone, environment, and role access inside the organization boundary.

SCIM provisioning is available for enterprise organizations with SAML SSO entitlement or an enabled SCIM enterprise add-on.

## Supported providers

MailSlurp supports standards-based SCIM 2.0 user and group provisioning.

- Microsoft Entra ID works with the MailSlurp SCIM tenant URL, bearer token, `/Users`, and `/Groups` endpoints.
- Okta and other SCIM-capable IdPs can connect with the same URL and bearer token model.
- Google Workspace can use SAML SSO with MailSlurp today. Generic outbound SCIM provisioning to a custom SCIM endpoint depends on the Google Workspace app and provisioning options available in your Google Admin tenant. If your Google Workspace setup exposes a SCIM connector for MailSlurp or a custom SCIM app, use the MailSlurp tenant URL and bearer token; otherwise use SAML SSO plus role mappings.

## Enable SCIM in MailSlurp

1. Sign in as the organization owner or an admin with organization SAML management permission.
2. Open the organization in the MailSlurp dashboard.
3. Go to `SCIM provisioning`.
4. Enable provisioning.
5. Create a SCIM bearer token and copy it immediately. The full token is only shown once.

![MailSlurp SCIM provisioning settings showing the organization tenant URL and provisioning controls](/examples-screenshots/ms2-app/organizations/enterprise/enterprise-scim-provisioning-setup.jpeg)

![MailSlurp SCIM bearer token screen showing a newly created one-time provisioning token](/examples-screenshots/ms2-app/organizations/enterprise/enterprise-scim-token-created.jpeg)

The tenant URL uses this format:

```text
https://api.mailslurp.com/scim/v2/{organizationSlug}
```

For staging or private environments, use the URL shown in the MailSlurp dashboard. The SCIM protocol endpoints require `Authorization: Bearer <token>` and `Content-Type: application/scim+json` for request bodies.

## Microsoft Entra ID setup

In Microsoft Entra admin center, configure MailSlurp as an enterprise application with automatic provisioning. If you already have a MailSlurp enterprise application, open it and start at the provisioning step.

### Create the Entra enterprise application

1. Open `Enterprise applications`.
2. Click `New application`.
3. Click `Create your own application`.
4. Enter a name such as `MailSlurp SCIM`.
5. Choose `Integrate any other application you don't find in the gallery (Non-gallery)`.
6. Click `Create`.

![Create a non-gallery enterprise application for MailSlurp SCIM in Microsoft Entra](/assets/entra-scim/01-entra-create-non-gallery-app.png)

### Connect Entra to the MailSlurp SCIM endpoint

Open the new enterprise application, then open `Provisioning`. In the new Entra provisioning experience, click `Connect your application` or `New configuration`.

![Microsoft Entra provisioning overview with the connect application action](/assets/entra-scim/03-entra-provisioning-overview.png)

Select `Bearer authentication`, paste the MailSlurp tenant URL into `Tenant URL`, and paste the SCIM bearer token into `Secret token`.

For production, the tenant URL is:

```text
https://api.mailslurp.com/scim/v2/{organizationSlug}
```

For staging or private environments, use the exact tenant URL shown in the MailSlurp dashboard.

![Microsoft Entra SCIM credentials with bearer authentication, tenant URL, and masked secret token](/assets/entra-scim/04-entra-scim-credentials-filled.png)

Click `Test connection`. When the connection succeeds, Entra enables `Create`.

![Microsoft Entra SCIM connection test complete with the Create button enabled](/assets/entra-scim/05-entra-test-connection-success.png)

Click `Create` to save the provisioning configuration.

![Microsoft Entra provisioning configuration created successfully](/assets/entra-scim/06-entra-provisioning-configuration-created.png)

### Review mappings and scoping

Open `Attribute mapping` and review the default user and group mappings. MailSlurp accepts Entra's standard SCIM user and group payloads, including `userName`, work email, display name, `externalId`, and `active`.

![Microsoft Entra attribute mapping showing user and group provisioning enabled](/assets/entra-scim/08-entra-attribute-mapping.png)

Open `Users and groups`, then click `Add user/group` and assign the users or groups Entra should provision into MailSlurp.

![Microsoft Entra users and groups assignment page for a MailSlurp SCIM application](/assets/entra-scim/09-entra-users-and-groups.png)

After assignments are ready, open `Provisioning`, set `Provisioning Status` to `On`, and click `Save`. Entra starts syncing assigned users and groups to the MailSlurp SCIM tenant URL.

![Microsoft Entra provisioning status control used to turn SCIM provisioning on](/assets/entra-scim/10-entra-start-provisioning.png)

Entra's connection test can query a random user with a SCIM filter. MailSlurp returns an empty SCIM `ListResponse` for users or groups that do not exist, so the test can pass before any users have been provisioned.

## User provisioning behavior

MailSlurp maps SCIM users to organization child accounts.

| SCIM field | MailSlurp behavior |
| --- | --- |
| `id` | MailSlurp user ID after creation |
| `externalId` | Stored for IdP correlation |
| `userName` | User email address |
| `emails[type eq "work"].value` or primary email | User email address when `userName` is omitted |
| `displayName` or `name.formatted` | User display name |
| `active` | `false` disables the MailSlurp account; `true` reactivates it |

When an IdP deactivates a user, MailSlurp disables that organization user. Disabled users cannot authenticate with their API key or dashboard session.

## Group provisioning and role sync

MailSlurp stores SCIM groups for the organization. Group role sync is optional and disabled by default.

To sync roles from IdP groups:

1. Create MailSlurp organization roles first.
2. Let your IdP provision groups into MailSlurp.
3. In `SCIM provisioning`, map each SCIM group to a MailSlurp role.
4. Enable `Group role sync`.

![MailSlurp SCIM group management screen showing provisioned IdP groups mapped to organization roles](/examples-screenshots/ms2-app/organizations/enterprise/enterprise-scim-group-role-sync.jpeg)

When role sync is enabled, group membership adds the mapped MailSlurp role to members of that SCIM group. When a user is removed from a SCIM group, MailSlurp removes the role assignment that SCIM created for that group.

## SCIM endpoint reference

MailSlurp implements these SCIM resources under the organization tenant URL:

- `GET /ServiceProviderConfig`
- `GET /ResourceTypes`
- `GET /ResourceTypes/User`
- `GET /ResourceTypes/Group`
- `GET /Schemas`
- `GET /Schemas/{schemaId}`
- `GET /Users`
- `POST /Users`
- `GET /Users/{id}`
- `PUT /Users/{id}`
- `PATCH /Users/{id}`
- `DELETE /Users/{id}`
- `GET /Groups`
- `POST /Groups`
- `GET /Groups/{id}`
- `PUT /Groups/{id}`
- `PATCH /Groups/{id}`
- `DELETE /Groups/{id}`

Supported filters:

- Users: `userName eq "name@example.com"` and `externalId eq "id-from-idp"`
- Groups: `displayName eq "Engineering"` and `externalId eq "id-from-idp"`

Supported PATCH operations are case-insensitive for `add`, `replace`, and `remove`, matching IdPs that send operation names as `Add`, `Replace`, or `Remove`.

## Related docs

- [Team accounts](/docs/organizations/)
- [SAML SSO setup](/docs/saml-sso/)
- [Entra SAML role mapping](/docs/entra-saml-role-mapping/)
- [Google Workspace SAML role mapping](/docs/google-workspace-saml-role-mapping/)
- [Roles and permissions](/docs/team-permissions/)