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, Rippling, and custom SCIM applications. If you use another Identity Provider, please let us know.

Generate your SCIM API token

Enterprise Plan admins 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 admin that only they can view.

Revoke tokens

When an admin leaves the workspace or is no longer an admin, their token will be revoked. When this happens, an automated message will be sent to the remaining admins of the workspace to notify them to replace the revoked token.

In addition, active tokens can be revoked by any of the admins 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.

Okta configuration

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

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.

  • Under the Provisioning tab, enable API integration.

  • Enter the Notion SCIM API token from your workspace into the API Token field.

  • Select "Email" for the Application username format on the Sign On application tab. Email addresses must be lower case.

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

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.

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.

    • Note: the user account cannot be deleted through SCIM. Account deletion must be done manually.

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


Up Next

Audit log

Your workspace audit log gives admins access to detailed information about security and safety-related activity. This can include identifying potential security issues, investigating suspicious behavior, and troubleshooting access.

Powered by Fruition