Provision users & groups with SCIM

Provision users & groups with SCIM - hero
In this Article

You can provision and manage users and groups in your Notion workspace with the System for Cross-domain Identity Management (SCIM) API standard 🔑


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.

Prerequisites for SCIM with Notion

  • 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

  • At least one domain has been verified by a Workspace Owner. Learn more about domain verification →

Generate your SCIM API token

Enterprise Plan Workspace owners can generate and view SCIM API tokens by going to Settings & membersSecurity & identitySCIM 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.

Revoke tokens

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.

Replace existing tokens

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.

Note: To avoid breaking existing integrations, make sure to replace any tokens associated with an admin before de-provisioning them.

Suppress invite emails

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 & membersIdentity & provisioningSCIM provisioningSuppress invite emails from SCIM provisioning. Toggle this setting on if you don’t want to send emails to users.

Azure

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

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

Note: Please refer to the Azure documentation for more information on planning your provisioning deployment.

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.

Note: This operation starts the initial synchronization cycle of all users and groups defined in Scope in the Settings section.

The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

Google

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

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

Note: Google’s SCIM integration does not support Group provisioning and de-provisioning.

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

Gusto

Reference Gusto for more detailed help in the setup process:

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

Okta

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.

Note: When updating users/groups via an existing SCIM configuration, please do not delete the Notion App from Okta. Doing so will remove all provisioned users from the workspace.

OneLogin

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

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

Note: If you plan to provision users to Notion via OneLogin, it’s important to configure SCIM before configuring SSO.

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.

Note: Workspace Owners can only copy and use tokens that they themselves have generated. If a token has already been created by another Workspace Owner, you can coordinate to determine if another token is necessary. All tokens will expire once the Workspace Owner that generated the token leaves the workspace or is downgraded to a Member.

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

Rippling

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

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

Note: You can only update a member's profile information if you have verified ownership of the user's email domain (this is typically the same as the email domains you have configured for SAML Single Sign-On with Notion). Verify your domain using the instructions here

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

Note: The workspace owner that created the SCIM bot token cannot be removed via the API. When a workspace owner is removed via the SCIM API, any tokens they created will be revoked and any integrations using that bot will be broken.

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

Note: Group deletion will be forbidden if it would result in no one having full access to one or more pages.


Give Feedback

Was this resource helpful?


Powered by Fruition