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

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.

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.

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.

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

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

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

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

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

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.

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