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