Get Notion free

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

Generate your SCIM API token

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.

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.

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.

If you run into any issues setting up provisioning with Okta, please contact us at team@makenotion.com.

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.

SCIM user attributes

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

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). Please contact us to verify a new email domain.

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

  • 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, e.g. GET <https://api.notion.com/scim/v2/Groups?startIndex=1&count=5>

    • 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