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

API Base URL https://api.contentful.com/scim/v2/organizations/{org_id}
This is a read/write API

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. Account settings

Note: If the user who holds the access token associated with your SCIM integration is removed or has their access rights diminished in your Contentful Organization, user and group provisioning will stop working. For this reason you may want to use a service account for this integration.

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"

Create a group