SCIM API
Introduction
System for Cross-domain Identity Management, or SCIM, is an API specification created to facilitate the management of people and groups of people in cloud-based applications and services.
Contentful's SCIM API is built on top of the SCIM 2.0 specification and can be integrated with major Identity Providers like Okta and OneLogin. It is possible to use our SCIM API to programatically create and manage organization memberships and teams within your Contentful organization.
To learn more about our SCIM support and to see the full list of supported Identity Providers, visit our FAQs.
Basic API information
https://api.contentful.com/scim/v2/organizations/{org_id}Authentication
To use the SCIM API you'll need an access token. This token will have the same rights as the owner of the account that generated it.
This account must have an Organization Membership in the Contentful organization where you intend to use the SCIM API. Its organization role should be either admin or owner.
We recommend that the organization role be set to owner.
Contentful recommends using Personal Access Tokens to manage SCIM API access. You can create personal access tokens in the Contentful web app. Go to the API Tokens section in the Account settings. Navigate to the Personal Access Tokens section and create a token.
Using the API
You can access the API securely via HTTPS.
The Authorization header with the type of Bearer must be used passing the access token when calling any of the methods in the API.
All API requests must specify a Content-Type header of application/scim+json.
Managing access to Spaces
It is not possible to manage space memberships directly via the SCIM API, but it is possible to use teams to manage access to spaces.
Contentful teams can be mapped to groups within the Identify Providers. See the Groups section below for details.
Reference
SCIM API endpoints
Note: The Contentful SCIM API follows the SCIM 2.0 specification and has many differences from other Contentful APIs.
Users
SCIM Users represent members of your Contentful organization.
You can create, update and list users with the SCIM API. Deactivating and removing users are currently not supported.
| SCIM Attribute | Contentful User Attribute |
Required | Mutability | Type |
|---|---|---|---|---|
userName |
email |
yes | immutable | String |
name.givenName |
firstName |
yes | immutable | String |
name.familyName |
lastName |
yes | immutable | String |
active |
- |
no | readOnly | Boolean |
emails |
email |
no | readOnly | Array |
Note: Other attributes supported by the SCIM specification will not be synchronized between Identity Providers and Contentful.
User
Get a single user
Update a single user with PUT
Updates attributes of the user.
Note: This endpoint is currently provided for identity provider compatibility, since no User attributes are mutable.
Update a single user with PATCH
Updates attributes of the user.
Note: This endpoint is currently provided for identity provider compatibility, since no User attributes are mutable.
Delete a single user
Use this endpoint to remove a user from your organization. Removing a user from your organization will also remove the user from all teams and spaces.
Note: The action does not delete the user's Contentful account, but only removes them from your organization.
Users collection
Get all users in the organization
It is possible to filter by the userName eq filter, passing a valid user email address as the value. See the Filtering section in the SCIM 2.0 specification for details.
GET /Users?filter=userName eq "user@example.com"Create a user
Newly created users will appear in your organization as "Invited". If you use the User Management API, you'll see the new Organization Membership with the status property of "pending".
The new users should receive an invitation email to join your Organization. In SSO enabled organizations, users will not receive this email notification.
All users are created with the organization role of member. Role changes are currently only supported via the User Management API or in the Contentful web app.
Groups
Teams in Contentful are referred to as groups in the SCIM specifications. You can create, remove and update teams with the SCIM API. You can also manage team members.
| Contentful Team Attribute | SCIM Group Attribute | Required | Type |
|---|---|---|---|
name |
displayName |
yes | String |
| ** | members |
no | Array |
Group
Get a single group
Update a single group
Use this endpoint to add, remove or replace team members.
Update request should contain the attribute Operations with a list of items of the following format:
| Property | Required | Type | Description |
|---|---|---|---|
op |
yes | String | One of add, remove or replace |
path |
yes | String | The affected attribute. Currently, the only accepted value is members |
value |
yes if adding or replacing members | Array | Currently, the only accepted value is a list of user references |
User references have the following structure:
| Property | Required | Type | Description |
|---|---|---|---|
display |
true | String | An identifier for the team member. It's normally the full name |
value |
true | String | The user ID |
For example, to add a new user to a group we would send the following request payload:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"display": "Kasia Kowalska",
"value": "1xGZIRXr2WPnsLkKfREo0z"
}
]
}
]
}It is also possible to run multiple different operations.
Delete a single group
Use this endpoint to remove a team from your organization. Removing a team from your organization will in addition remove its team memberships. Any team space memberships associated with the team will also be removed.
Groups collection
Get all groups in the organization
It is possible to filter by the displayName eq filter, passing a valid group name as the value. See the Filtering section in the SCIM 2.0 specification for details.
GET /Groups?filter=displayName eq "My Group"