# Set up SCIM provisioning for the Dashboard

Source: https://developer.nylas.com/docs/dev-guide/dashboard-saml-sso/scim-provisioning/

> **Info:** 
> **SCIM provisioning is an enterprise feature.** If the **Provisioning** step is not visible in your SAML SSO settings, contact your customer success partner to have it enabled for your organization.


> **Info:** 
> **This is for Dashboard organization login.** If you want to let your app's end users authenticate with an external IdP, see [Nylas Connect external IdP](/docs/v3/auth/nylas-connect/use-external-idp/) instead.


Use SCIM to let your identity provider (IdP) manage Nylas Dashboard membership automatically. When you provision a user in Okta or Microsoft Entra ID, they get a Dashboard account; when you deactivate them, their Dashboard sessions are revoked within seconds. SCIM builds on your existing [SAML SSO setup](/docs/dev-guide/dashboard-saml-sso/) and uses the same **Provisioning** step in the SAML SSO settings.

## What is SCIM provisioning?

SCIM (System for Cross-domain Identity Management) is an open standard, defined in RFC 7644 and published in 2015, for syncing user accounts between an identity provider and an application. With SCIM enabled, your IdP pushes user create, update, and deactivate events to Nylas over authenticated HTTP requests, so Dashboard membership stays in sync with your directory without manual invites or removals.

The main reason enterprises adopt SCIM is offboarding. SAML SSO alone handles login, but a former employee keeps their Dashboard account until someone removes it by hand. With SCIM, deactivating a user in your IdP soft-deletes their organization membership and revokes every active session immediately, closing the gap where old access lingers after someone leaves.

## Before you begin

SCIM sits on top of SAML SSO, so you complete the SAML steps first. You need **Admin** or **Owner** access on the Nylas organization, a verified company domain, and a saved IdP metadata configuration. The **Generate token** button stays disabled until both a verified domain and a connected IdP exist.


> **Info:** 
> **Where to find SAML settings:** In the [Nylas Dashboard](https://dashboard-v3.nylas.com), click your organization name in the top-left, then go to **Settings** in the sidebar. Select the **SAML SSO** tab (direct link: [dashboard-v3.nylas.com/organization/settings/identity](https://dashboard-v3.nylas.com/organization/settings/identity)).
> 
> You must have **Admin** or **Owner** access to see this tab.


Confirm these three prerequisites before configuring SCIM:

- At least one **verified** company domain (the **Verify your company domain** step shows a green checkmark).
- A saved IdP configuration (the **Connect your identity provider** step shows your **Connected IdP** card). See [Custom SAML](/docs/dev-guide/dashboard-saml-sso/connect-idp/).
- An IdP that supports SCIM 2.0 provisioning, such as Okta or Microsoft Entra ID.

## Generate a SCIM bearer token

Your IdP authenticates to the Nylas SCIM endpoint with a bearer token. Each token is generated from 32 bytes of cryptographically secure randomness and stored only as a salted HMAC-SHA256 hash, so the Dashboard shows the full value once and can never display or recover it later. Generate one token per IdP integration and give each a description so you can tell them apart.

1. Open **Settings > SAML SSO** in the [Nylas Dashboard](https://dashboard-v3.nylas.com/organization/settings/identity) and expand the **Provisioning** step.
2. Copy the **SCIM base URL** shown at the top of the step. It looks like `https://dashboard-api.nylas.com/scim/v2`. You paste this into your IdP.
3. Click **Generate token**. Add an optional description (for example, `Okta production`) and click **Generate**.
4. Copy the token from the **Save your SCIM token** dialog. This is the only time the full value appears.
5. Select **I have saved this token in a secure location**, then click **Done**.

Generated tokens appear in the **Bearer tokens** table with their prefix, description, creation date, and last-used time. To retire a token, click **Revoke**. Revocation takes effect immediately, and the next SCIM request using that token returns `401 Unauthorized`.

## Set up SCIM in Okta

Okta pushes user lifecycle events to Nylas once you enable API integration on the same app you created for SAML. Provisioning to the app supports three actions: create users, update user attributes, and deactivate users. Assign users or groups to the app, then run an import so Okta reconciles its directory with your organization.

1. In the Okta Admin Console, open the app you created for SAML and go to the **Provisioning** tab.
2. Click **Configure API Integration** and select **Enable API integration**.
3. Paste the values from the Nylas **Provisioning** step:
   - **Base URL**: the SCIM base URL, for example `https://dashboard-api.nylas.com/scim/v2`.
   - **API Token**: the bearer token you generated.
4. Click **Test API Credentials** to confirm Okta can reach the endpoint, then **Save**.
5. Under **Provisioning > To App**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.
6. On the **Assignments** tab, assign the users or groups that should have Dashboard access.
7. Run **Provisioning > Import** or wait for the next sync cycle.

Okta's default attribute mappings work without changes across the 3 user fields Nylas reads: it sends `userName` as the work email, `givenName` as the first name, and `familyName` as the last name.

## Set up SCIM in Microsoft Entra ID

Microsoft Entra ID (formerly Azure AD) provisions users through the same enterprise application you used for SAML. Entra sends a `GET /scim/v2/ServiceProviderConfig` request when you test the connection, so a successful test confirms the token and base URL are correct before any users sync.

1. In the Azure portal, open **Enterprise applications**, select your Nylas application, and open the **Provisioning** blade.
2. Set **Provisioning Mode** to **Automatic**.
3. Under **Admin Credentials**, enter:
   - **Tenant URL**: the SCIM base URL, for example `https://dashboard-api.nylas.com/scim/v2`.
   - **Secret Token**: the bearer token you generated.
4. Click **Test Connection**, then **Save**.
5. Under **Mappings**, confirm the **Provision Azure Active Directory Users** mapping sends `userPrincipalName` to `userName`, `givenName` to `name.givenName`, and `surname` to `name.familyName`.
6. Assign users under **Users and groups**, then set provisioning **Status** to **On**.

Entra runs an initial cycle within about 40 minutes of turning provisioning on, then syncs on a recurring schedule. Deactivating or unassigning a user sends a deprovision request to Nylas on the next cycle.

## How provisioning and deprovisioning work

Each SCIM operation from your IdP maps to a specific change in your Nylas organization. Provisioning creates the account and adds it to the org with your configured default role; deprovisioning removes org access and revokes sessions. The full deactivation-to-session-revocation path completes in seconds, not on a delayed batch job.

| IdP action | Nylas behavior |
|---|---|
| `POST /scim/v2/Users` | Creates the user, adds them to the org with the default role, and marks them provisioned by SCIM. |
| `PATCH` with `active: false` | Sets the user inactive, soft-deletes org membership, and revokes all active sessions immediately. |
| `PATCH` with `active: true` | Restores org membership with the previous role. |
| `DELETE /scim/v2/Users/{id}` | Removes org access and revokes sessions, same as deactivation. |
| `GET /scim/v2/Users` | Lists users scoped to the token's organization, with filter and pagination support. |

SCIM-provisioned users show a **Managed by SSO** badge on the organization **Members** page. Nylas maps 4 fields from each SCIM user to the member record: `userName` becomes the email address (lowercased), `name.givenName` the first name, `name.familyName` the last name, and the SCIM `id` is stored as the external ID for reconciliation.

## Supported SCIM operations

The Nylas SCIM server implements the RFC 7644 User resource and the ServiceProviderConfig discovery endpoint. It supports full user lifecycle management, filtering by `userName`, and pagination. Group provisioning is not available, so map IdP groups to Dashboard roles through [SAML group-to-role mapping](/docs/dev-guide/dashboard-saml-sso/) instead.

| Capability | Supported |
|---|---|
| Create, read, replace, update, delete users | Yes |
| Filter by `userName eq "user@example.com"` | Yes |
| Pagination with `startIndex` and `count` | Yes |
| `ServiceProviderConfig` discovery | Yes |
| Group provisioning (`/scim/v2/Groups`) | No |
| Bulk operations | No |
| `changePassword` | No |

Nylas rate-limits SCIM requests per organization to 200 read and 60 write requests per minute. Most IdP sync cycles stay well under these limits; if you hit them during a large initial import, the IdP retries on its next cycle.

## Google Workspace and SCIM

Google Workspace does not expose a native SCIM client for custom SAML applications, so it cannot push provisioning events to Nylas directly. The 2 providers with native SCIM support in this guide, Okta and Microsoft Entra ID, can broker Google Workspace, or you can rely on SAML for onboarding.

- **Rely on SAML JIT provisioning.** With just-in-time provisioning enabled, a user's Dashboard account is created on their first SAML login. This covers onboarding, but it does not deprovision users automatically when they leave.
- **Broker through Okta or Entra ID.** Some organizations federate Google Workspace into Okta or Microsoft Entra ID and run SCIM from there, which restores automatic deprovisioning.

For onboarding-only automation, [JIT provisioning](/docs/dev-guide/dashboard-saml-sso/) in the **Manage user access** step is the simplest path for Google Workspace.

## Troubleshoot SCIM provisioning

Most SCIM issues trace back to the bearer token, the base URL, or a user who already exists in the org through another path. Use the table below to map a symptom to a fix. A `401` almost always means the token is wrong or revoked, and a `409` means the user is already a member. If a large initial import stalls, remember the endpoint caps writes at 60 requests per minute per organization and the IdP retries on its next cycle.

| Symptom | Likely cause | What to do |
|---|---|---|
| IdP returns `401 Unauthorized` | Token is invalid, revoked, or mistyped | Generate a new token in the **Provisioning** step and update the secret in your IdP. Confirm there is no trailing space. |
| Test connection fails in the IdP | Wrong base URL | Copy the **SCIM base URL** from the Provisioning step exactly. It ends in `/scim/v2` with no trailing slash. |
| `409` conflict when creating a user | The user is already in the org through an invite or SAML login | Remove the existing member first, or let them link via SAML login instead of provisioning through SCIM. |
| User deactivated in the IdP but still sees data | The browser has a cached page | Deactivation revokes server-side sessions immediately; the client shows an error on the next request or page refresh. |
| Filter query returns nothing | Unsupported filter expression | Only `userName eq "..."` is supported. Requests with other filter attributes return `400`. |
| **Provisioning** step is not visible | The feature is not enabled for the org | SCIM is an enterprise feature. Contact your customer success partner to enable it. |

## What's next

- [Configure SAML SSO](/docs/dev-guide/dashboard-saml-sso/): Complete domain verification and IdP setup, the prerequisites for SCIM.
- [Custom SAML](/docs/dev-guide/dashboard-saml-sso/connect-idp/): Reference for service provider values and required attributes.
- [Troubleshooting](/docs/dev-guide/dashboard-saml-sso/troubleshooting/): Fix common SAML setup and login errors.