Lazy loaded image
Provision Users and Groups with SCIM🚧
00 分钟
2022-3-25
分類
👤
帳號設定與隱私（Account Settings & Privacy）
狀態
Last edited by
負責編輯人
最後更新
You can provision and manage users and groups in your Notion workspace with the System for Cross-domain Identity Management (SCIM) API standard.
👉
Note: Notion's SCIM API is only available for workspaces on Notion's Enterprise Plan. Contact sales to learn more →
 
What you can do with Notion's SCIM APIHow to setup provisioning with SCIMRetrieving your SCIM API keySetting up Provisioning with OktaFeaturesRequirementsStep­-by­-Step Configuration InstructionsTroubleshootingNotion SCIM API EndpointsService Provider ConfigurationGET /ServiceProviderConfigGET /ResourceTypesUsersGET /UsersGET /Users/<id>POST /UsersPATCH /Users/<id>PUT /Users/<id>DELETE /Users/<id>GroupsGET /GroupsGET /Groups/<id>POST /GroupsPATCH /Groups/<id>PUT /Groups/<id>DELETE /Groups/<id>Related guides

What you can do with Notion's SCIM API

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.
 

How to setup provisioning with SCIM

We currently support Okta, Rippling, and custom SCIM applications (see our SCIM API below for details). If you use another Identity Provider, please let us know.
 

Retrieving your SCIM API key

Please contact your Notion rep to generate an API key for the Notion workspace you want to provision.
You can then go to your Notion workspace, open Settings & Members, select the Security & SAML tab, and then under the SCIM configuration section choose View token. Only workspace admins can view the API key.
notion image
 

Setting up Provisioning with Okta

Features

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 (Removes user from your Notion workspace)
  • Push Groups
 

Requirements

Provisioning through Okta is available for workspaces on Notion's Enterprise Plan.
Please contact your Notion rep to generate an API key for the Notion workspace you want to provision.
Retrieve the SCIM API token for your Notion workspace:
  • You need to be a workspace administrator to access the SCIM API token.
  • Click on Settings & Members in your left sidebar. Then click on the Security & SAML tab.
  • Scroll down to the bottom to the SCIM configuration section and click on View Token.
      • notion image
       

Step­-by­-Step Configuration Instructions

👉
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.
Add the Notion app from Okta's Integrations Directory. Under the Provisioning tab, enable API integration. Enter the Notion SCIM API token from the previous step into the API Token field.
notion image
Select "Email" for the Application username format on the Sign On application tab.
notion image
 
Provisioning Groups
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.
notion image
 

Troubleshooting

Please ensure the Okta username attribute is set to Email, and that the email address is lowercase.
ℹ️
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.
If you run into any issues setting up provisioning with Okta, please contact us.
 

Notion SCIM API Endpoints

ℹ️
Notion's SCIM API adheres to the SCIM 2.0 protocol.

Service Provider Configuration

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.

Users

The following table describes the mapping between SCIM user attributes and Notion user profile fields. Other user attributes will be ignored.
Copy of User Attributes
SCIM Attribute
Notion User Profile Field
Required
username
Email
Required
name.givenName
First Name
Required
name.familyName
Last Name
Required

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

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. The 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.
ℹ️
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).

PUT /Users/<id>

PUT https://api.notion.com/scim/v2/Users/<id>
Update , and returns the updated user record.
ℹ️
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).

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.

Groups

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.
ℹ️
Group deletion will be forbidden if it is to result in no one having full access to one or more pages.

Related guides

Notion for teams
 
 
Video preview
上一篇
读书盘点｜2022年世界读书日
下一篇
第三周刊_No.34｜母女之间：阿克曼、波伏瓦、费兰特，她们这样书写母亲