Set up SCIM provisioning for the Dashboard

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

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

Open Settings > SAML SSO in the Nylas Dashboard and expand the Provisioning step.
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.
Click Generate token. Add an optional description (for example, Okta production) and click Generate.
Copy the token from the Save your SCIM token dialog. This is the only time the full value appears.
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.

In the Okta Admin Console, open the app you created for SAML and go to the Provisioning tab.
Click Configure API Integration and select Enable API integration.
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.
Click Test API Credentials to confirm Okta can reach the endpoint, then Save.
Under Provisioning > To App, enable Create Users, Update User Attributes, and Deactivate Users.
On the Assignments tab, assign the users or groups that should have Dashboard access.
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.

In the Azure portal, open Enterprise applications, select your Nylas application, and open the Provisioning blade.
Set Provisioning Mode to Automatic.
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.
Click Test Connection, then Save.
Under Mappings, confirm the Provision Azure Active Directory Users mapping sends userPrincipalName to userName, givenName to name.givenName, and surname to name.familyName.
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 instead.

Capability	Supported
Create, read, replace, update, delete users	Yes
Filter by `userName eq "[email protected]"`	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 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: Complete domain verification and IdP setup, the prerequisites for SCIM.
Custom SAML: Reference for service provider values and required attributes.
Troubleshooting: Fix common SAML setup and login errors.