Provision users & groups with SCIM
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, and custom SCIM applications. If you use another Identity Provider, please let us know.
Prerequisites for SCIM with Notion
Your workspace must be on an Enterprise Plan.
Your Identity Provider (IdP) must support the SAML 2.0 protocol.
Only a workspace owner can configure SCIM for a Notion workspace.
If you want to use SCIM to modify a user's name or email address, you must have verified ownership over their email domain. Learn more about domain verification →
Generate your SCIM API token
Enterprise Plan workspace owners can generate and view SCIM API tokens by going to Settings & members
→ Identity & provisioning
→ SCIM provisioning
.
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.
Suppress invite emails
To control whether users will receive invitations to workspaces and groups via email when provisioned by SCIM, Enterprise Plan workspaces owners can go to Settings & members
→ Identity & provisioning
→ SCIM provisioning
→ Suppress invite emails from SCIM provisioning
. Toggle this setting on 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.
Azure
For additional instructions, you can also reference the documentation in the Azure Active Directory Help Center:
Notion’s Azure SCIM integration supports the following provisioning features:
Create users
Remove users
Keep user attributes synchronized between Azure AD and Notion.
Provision groups and group memberships in Notion.
Single sign-on to Notion (recommended).
Note: Please refer to the Azure documentation for more information on planning your provisioning deployment.
Step 1: Configure Notion to support provisioning with Azure AD
Login to your Notion Workspace, open the
Settings & members
→Identity & provisioning
tab and scroll down to theSCIM provisioning
section.If a token hasn’t already been generated, click
+ Add token
and copy the token. You’ll enter this token as your Secret Token in step 5.5.Notion’s SCIM tenant URL is https://www.notion.so/scim/v2, which you’ll use in step 5.5.
Step 2: Add Notion from the Azure AD application gallery
Follow instructions for adding an application from the gallery here.
The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user/group.
If you choose to scope who will be provisioned to your app based on assignment, you can use the following steps to assign users and groups to the application.
If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described here.
Step 3: Configure automatic user provisioning to Notion
Sign in to the Azure portal. Select
Enterprise Applications
, then selectAll applications
.In the applications list, select
Notion
.Select the
Provisioning
tab.Set the
Provisioning Mode
toAutomatic
.Under the
Admin Credentials
section, input your Notion Tenant URL and Secret Token. ClickTest Connection
to ensure Azure AD can connect to Notion. If the connection fails, ensure your Notion account has Admin permissions and try again.Select
Save
.Under the
Mappings
section, selectSynchronize Azure Active Directory Users to Notion
.Review the user attributes that are synchronized from Azure AD to Notion in the
Attribute-Mapping
section. Select theSave
button to commit any changes.
Under the
Mappings
section, selectSynchronize Azure Active Directory Groups to Notion
.Review the group attributes that are synchronized from Azure AD to Notion in the
Attribute-Mapping
section. Select theSave
button to commit any changes.
To enable the Azure AD provisioning service for Notion, change the
Provisioning Status
toOn
in theSettings
section.Define the users and/or groups that you would like to provision to Notion by choosing the desired values in
Scope
in theSettings
section.When you're ready to provision, click
Save
.
Note: This operation starts the initial synchronization cycle of all users and groups defined in Scope
in the Settings
section.
The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.
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 theIdentity & provisioning
tab.Scroll down to the
SCIM provisioning
section (your available SCIM tokens will be listed).In the SCIM tokens table, either click
Copy
next to an existing token OR clickAdd token
in the right corner to create a new token.
Step 2: Configuring provisioning in Google
Make sure you’re signed into an administrator account to ensure your user account has the appropriate permissions.
Continue the steps shown on Google Workspace Admin Help starting at Set up auto-provisioning for the Notion application.
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 & members
tab, then select theIdentity & provisioning
tab.Scroll down to the
SAML Single sign-on (SSO)
section.Open the
Edit SAML SSO configuration
buttonClick copy link next to the
Assertion Consumer Service (ACS) URL
. Paste it somewhere to be retrieved later.Go to back to
Settings & members
→Identity & provisioning
and scroll down to theSCIM 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, selectEmail
for theApplication username
format on theSign On application
tab.Under the
Provisioning
tab, selectConfigure API integration
, and click on theEnable API integration
checkbox.Enter the Notion SCIM API token you copied in Step 1 into the
API Token
text box, and selectSave
.Click on the
Edit
button next to Provisioning to App header, and enable your preferred features: Create users, Update user attributes, or Deactivate users. ClickSave
.After setting up the API integration, open the
Push Groups
tab, and add the Okta groups you want to sync with Notion from thePush 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.
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 & members
, then select theIdentity & 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 & members
, then select theIdentity & provisioning
tab and scroll down to theSCIM 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
box.Paste the
SCIM API token
into theSCIM Bearer Token
box.Click
Enable
.Go to the
Provisioning
tab.Under
Workflow
, checkEnable provisioning
.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.
GET /Users
GET <https://api.notion.com/scim/v2/Users>
Retrieve a paginated list of workspace members.
You can paginate using the
startIndex
andcount
parameters. Note thatstartIndex
is 1-indexed and count has a maximum of 100.You can filter the results with the
filter
parameter. Valid attributes to filter by areemail
,given_name
, andfamily_name
, e.g.GET <https://api.notion.com/scim/v2/Users?startIndex=1&count=50&filter=email> eq [email protected]
Note that
given_name
andfamily_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
andmeta.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). Verify your domain using the instructions here →
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 tofalse
by sending aPATCH /Users/<id>
or aPUT /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.
Note: You can assign workspace levels to Users
using the role
attribute, which is an extension of the existing User schema. The format is:
"urn:ietf:params:scim:schemas:extension:notion:2.0:User": { role: string // "owner" | "membership_admin" | "member" }
GET /Groups
GET <https://api.notion.com/scim/v2/Groups>
Retrieve a paginated list of workspace groups.
You can paginate using the
startIndex
andcount
parameters. Note thatstartIndex
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 theirdisplayName
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.