Provision users & groups with SCIM

Notion’s SCIM API allows you to do the following:

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

• Create and remove groups in your workspace.

• Add and remove members in a group.

• Retrieve the groups in your workspace.

• Find groups by name.

We currently support Okta, OneLogin, Rippling, and custom SCIM applications. If you use another Identity Provider, please let us know. See instructions for Identity Provider setup for specific apps here →

To use SCIM with Notion:

• Your workspace must be on an Enterprise Plan.

• Your Identity Provider (IdP) must support the SAML 2.0 protocol. See instructions for Identity Provider setup for specific apps here →

• A workspace owner must configure SCIM for the Notion workspace.

• You must have verified ownership over an email domain if you want to use SCIM to modify a user's name or email address. Learn more about domain verification →

Only Enterprise Plan workspace owners can generate and view SCIM API tokens. To create a SCIM API token:

1. Go to Settings → Identity & provisioning → SCIM provisioning.

2. Select New token.

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.

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.

To control whether users will receive invitations to workspaces and groups via email when provisioned by SCIM, Enterprise Plan workspaces owners can:

1. Go to Settings → Identity & provisioning → SCIM provisioning.

2. Toggle on Suppress invite emails from SCIM provisioning if you don’t want to send emails to users.

• 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 and count has a maximum of 100.

  • 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 [email protected]

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

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

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