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