Provision users & groups with SCIM

User provisioning and management:

• Create and remove members in your workspace.

• Update a member's profile information.

• Retrieve the members in your workspace.

  • Find members by email or name.

Group provisioning and management:

• Create and remove groups in your workspace.

• Add and remove members in a group.

• Retrieve the groups in your workspace.

  • Find groups by name.

Not supported:

• Managing workspace guests.

We currently support Okta, OneLogin, Rippling, Gusto and custom SCIM applications. If you use another Identity Provider, please let us know.

• Your workspace must be on an Enterprise plan

• Your Identity Provider (IdP) must support the SAML 2.0 protocol

• Only a Workspace Owner can configure SCIM for a Notion workspace

• If you want to use SCIM to modify a user's name or email address, you must have verified ownership over their email domain. Learn more about domain verification →

Enterprise Plan Workspace owners can generate and view SCIM API tokens by going to Settings & members → Security & identity → SCIM configuration.

• To generate a new token, click on the + New Token button in the right corner.

• A unique token is generated for each Workspace owner that only they can view.

When a Workspace owner leaves the workspace or their role is changed, their token will be revoked. When this happens, an automated message will be sent to the remaining Workspace owners to notify them to replace the revoked token.

In addition, active tokens can be revoked by any of the Workspace owners in the workspace. To revoke a token, click the 🗑 alongside the respective token.

If a token is revoked, you will need to replace it in any existing integrations.

Any SCIM integration and user provisioning relying on the revoked token will be disabled until it is replaced by an active token.

To control whether users will receive invitations to workspaces and groups via email when provisioned by SCIM, enterprise plan workspaces owners can go to Settings & members → Identity & provisioning → SCIM provisioning → Suppress invite emails from SCIM provisioning. Toggle this setting on if you don’t want to send emails to users.

• GET /ServiceProviderConfig

  • GET <https://api.notion.com/scim/v2/ServiceProviderConfig>

  • Retrieve a description of the SCIM specification features available.

  • Defined in Section 5 of the SCIM Protocol Specification.

• GET /ResourceTypes

  • GET <https://api.notion.com/scim/v2/ResourceTypes>

  • Retrieve a list of the SCIM resource types available.

  • Defined in Section 6 of the SCIM Protocol Specification.

For additional instructions, you can also reference the documentation in the Azure Active Directory Help Center:

• Configuring Notion for automatic user provisioning

Notion’s Azure SCIM integration supports the following provisioning features:

• Create users

• Remove users

• Keep user attributes synchronized between Azure AD and Notion.

• Provision groups and group memberships in Notion.

• Single sign-on to Notion (recommended).

Step 1: Configure Notion to support provisioning with Azure AD

• Login to your Notion Workspace, open the 

  Settings & members → Identity & Provisioning tab and scroll down to the SCIM provisioning section.

• If a token hasn’t already been generated, click 

  + Add token and copy the token. You’ll enter this token as your Secret Token in step 5.5.

• Notion’s SCIM tenant URL is https://www.notion.so/scim/v2, which you’ll use in step 5.5.

Step 2: Add Notion from the Azure AD application gallery

• Follow instructions for adding an application from the gallery here.

The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user/group.

• If you choose to scope who will be provisioned to your app based on assignment, you can use the following steps to assign users and groups to the application.

• If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described here.

Step 3: Configure automatic user provisioning to Notion

• Sign in to the Azure portal. Select Enterprise Applications, then select All applications.

• In the applications list, select Notion.

• Select the Provisioning tab.

• Set the Provisioning Mode to Automatic.

• Under the Admin Credentials section, input your Notion Tenant URL and Secret Token. Click Test Connection to ensure Azure AD can connect to Notion. If the connection fails, ensure your Notion account has Admin permissions and try again.

• Select Save.

• Under the Mappings section, select Synchronize Azure Active Directory Users to Notion.

  • Review the user attributes that are synchronized from Azure AD to Notion in the Attribute-Mapping section. Select the Save button to commit any changes.

• Under the Mappings section, select Synchronize Azure Active Directory Groups to Notion.

  • Review the group attributes that are synchronized from Azure AD to Notion in the Attribute-Mapping section. Select the Save button to commit any changes.

• To enable the Azure AD provisioning service for Notion, change the Provisioning Status to On in the Settings section.

• Define the users and/or groups that you would like to provision to Notion by choosing the desired values in Scope in the Settings section.

• When you're ready to provision, click Save.

For additional instructions, you can also reference the documentation in the Google Workspace Admin Help Center:

• Configure Notion user provisioning

Notion’s Google SCIM integration supports the following provisioning features:

• Create users

• Update user attributes (if the user has an email domain belonging to your organization)

• Deactivate users (this removes users from your Notion workspace(s))

Step 1: Enabling user provisioning in Notion

• Go to the Settings & members tab, then select the Identity & provisioning tab

• Scroll down to the SCIM configuration section (your available SCIM tokens will be listed)

• In the SCIM tokens table, either click Copy next to an existing token OR click Add Token in the right corner to create a new token

Step 2: Configuring provisioning in Google

• Make sure you’re signed into an administrator account to ensure your user account has the appropriate permissions

• Continue the steps shown on Google Workspace Admin Help starting at Set up auto-provisioning for the Notion application

Reference Gusto for more detailed help in the setup process:

• Gusto integrates with Notion

Step 1: Click Connect and follow the instructions to verify your account credentials

• In your Notion sidebar, go to Settings & members -> Identity & provisioning

• Under SCIM provisioning, click Add Token and copy the token

• On Gusto, paste the token in the SCIM API key field and enter your Notion account email

Step 2: Match Notion user accounts with your team members in Gusto

Notion's Okta Integration supports the following provisioning features:

• Create Users

• Update User Attributes (if the user has an email domain belonging to your organization)

• Deactivate Users (this removes users from your Notion workspace)

• Push Groups

Step 1: Enabling provisioning in Notion

• Go to Settings and Members tab, then select the Identity & Provisioning tab

• Scroll down to the SAML Single sign-on (SSO) section

• Open the Edit SAML SSO configuration button

• Click copy link next to the Assertion Consumer Service (ACS) URL. Paste it somewhere to be retrieved later.

• Go to back to Settings and Members → Identity & Provisioning and scroll down to the SCIM provisioning section

• If a token hasn’t already been generated, click + Add token and copy the token. Paste it somewhere to be retrieved later.

Step 2: Configuring provisioning in Okta

• Add the Notion app from Okta's app catalog Directory.

• In the Sign-on Options view, select "Email" for the Application username format on the Sign On application tab.

• Under the Provisioning tab, select Configure API integration, and click on the Enable API integration checkbox.

• Enter the Notion SCIM API token you copied in Step 1 into the API Token text box, and select Save.

• Click on the Edit button next to Provisioning to App header, and enable your preferred features: Create users, Update user attributes, or Deactivate users. Click Save.

• After setting up the API integration, open the Push Groups tab, and add the Okta groups you want to sync with Notion from the "Push Groups" button.

For additional documentation, you can also reference steps on OneLogin’s website here:

• Provisioning Users to Notion

Notion’s OneLogin Integration supports the following provisioning features:

• Create Users

• Update User Attributes (if the user has an email domain belonging to your organization)

• Deactivate Users (this removes users from your Notion workspace)

• Create Rules to map OneLogin Roles with permission groups in Notion

Step 1: Enabling provisioning in Notion

• Go to Settings and Members tab, then select the Identity & Provisioning tab.

• Scroll down to the SAML Single sign-on (SSO) section.

• Open the Edit SAML SSO configuration button.

• Click copy link next to the Assertion Consumer Service (ACS) URL. Paste it somewhere to be retrieved later.

• Go to back to Settings and Members → Identity & Provisioning and scroll down to the SCIM provisioning section

• If a token hasn’t already been generated, click + Add token and copy the token. Paste it somewhere to be retrieved later.

Step 2: Configuring provisioning in OneLogin

• Go to Administration → Applications → Applications

• Click the Add App button, search for Notion in the search box, and select the SAML 2.0 version of Notion.

• Click Save

• Go to the Configurations tab

• Paste the Assertion Consumer Service (ACL) URL into the Consumer URL textbox

• Paste the SCIM API token into the SCIM Bearer Token textbox

• Click Enable

• Go to the Provisioning tab

• Check Enable provisioning under Workflow

• Click the Save button in the upper right corner

• (optional) Enable or disable requirement for admin approval when users are created, deleted, or updated under Require admin approval before this this action is performed

• (optional) Select what happens to a user in Notion when that user is deleted from OneLogin. Choose between Delete (removes the user from the Notion workspace) or Do Nothing.

• Click the Save button in the upper right corner

For detailed documentation, you can reference Rippling's website here:

• Rippling App Shop — Notion

The table below outlines the mapping between SCIM user attributes and Notion user profile fields. Other user attributes will be ignored.

• GET /Users

  • GET <https://api.notion.com/scim/v2/Users>

  • Retrieve a paginated list of workspace members.

  • You can paginate using the startIndex and count parameters. Note that startIndex is 1-indexed.

  • You can filter the results with the filter parameter. Valid attributes to filter by are email, given_name, and family_name, e.g. GET <https://api.notion.com/scim/v2/Users?startIndex=1&count=50&filter=email> eq employee@acmecorp.com

  • Note that given_name and family_name are case sensitive. Email is converted to lowercase.

• GET /Users/<id>

  • GET <https://api.notion.com/scim/v2/Users/><id>

  • Retrieve a specific workspace member by its Notion user ID. This will be an UUID with 32 characters in the following format: 00000000-0000-0000-0000-000000000000.

  • Note that meta.created and meta.lastModified do not reflect meaningful timestamp values.

• POST /Users

  • POST <https://api.notion.com/scim/v2/Users>

  • If the user you are adding already has a Notion user account with the same email, then they will be added to your workspace.

  • If the user does not exist, calling this will create a new Notion user and then add that user to your workspace. They will be mapped to the Notion user profile that is created.

• PATCH /Users/<id>

  • PATCH <https://api.notion.com/scim/v2/Users/><id>

  • Update through a series of operations, and returns the updated user record.

• PUT /Users/<id>

  • PUT <https://api.notion.com/scim/v2/Users/><id>

  • Update, and returns the updated user record.

• DELETE /Users/<id>

  • DELETE <https://api.notion.com/scim/v2/Users/><id>

  • Remove a user from your workspace. The user is logged out of all active sessions.

    • The user account cannot be deleted through SCIM. Account deletion must be done manually.

    • Removing a user from your workspace can also be achieved by setting the active user attribute to false by sending a PATCH /Users/<id> or a PUT /Users/<id> request.

• GET /Groups

  • GET <https://api.notion.com/scim/v2/Groups>

  • Retrieve a paginated list of workspace groups.

  • You can paginate using the startIndex and count parameters. Note that startIndex is 1-indexed and count has a maximum of 100, e.g. GET <https://api.notion.com/scim/v2/Groups?startIndex=1&count=5>

    • If pagination is not used, a maximum of 100 workspace groups will be returned in a request.

  • You can filter the results with the filter parameter. Groups can be filtered by their displayName attribute, e.g. GET <https://api.notion.com/scim/v2/Groups?filter=displayName> eq Designers

• GET /Groups/<id>

  • GET <https://api.notion.com/scim/v2/Groups/><id>

  • Retrieve a specific workspace group by its Notion group ID. This will be an UUID with 32 characters in the following format: 00000000-0000-0000-0000-000000000000.

• POST /Groups

  • POST <https://api.notion.com/scim/v2/Groups>

  • Create a new workspace group.

• PATCH /Groups/<id>

  • PATCH <https://api.notion.com/scim/v2/Groups/><id>

  • Update a workspace group through a series of operations.

• PUT /Groups/<id>

  • PUT <https://api.notion.com/scim/v2/Groups/><id>

  • Update a workspace group.

• DELETE /Groups/<id>

  • DELETE <https://api.notion.com/scim/v2/Groups/><id>

  • Delete a workspace group.