System for Cross-domain Identity Management (SCIM)^Beta

[API version: 2.0]

Introduction

Base URL

For US region: https://auth-api.contentstack.com

For European region: https://eu-auth-api.contentstack.com

Overview

Contentstack is a headless, API-first content management system (CMS) that provides everything you need to power your web or mobile properties. To learn more about Contentstack, visit our website or refer to our documentation site to understand what we do.

This document is a detailed reference to the beta version of Contentstack’s SCIM API.

The SCIM API helps businesses to manage their users in their Contentstack organization via an IdP client. This includes provisioning (adding) and deprovisioning (removing) users in a Contentstack Organization via IdP client, and assigning permissions to these users via group mapping in Contentstack.

Contentstack SCIM API is built using SCIM 2.0 protocol. Currently, we extend our SCIM’s support to OneLogin, but you can write your custom tools that can use Contentstack’s SCIM API.

Note: Before using the SCIM API requests, make sure you have enabled SCIM in the SCIM 2.0 section of your Organization Settings page.

Authentication

To use the SCIM API, you need to first authenticate yourself with your IdP client and generate its access token.

API conventions

The base URL for Content Management API is auth-api.contentstack.com and for the European region, the base URL is eu-auth-api.contentstack.com.
The SCIM API version (in our case, 'v2.0') can be found in the URL, e.g. auth-api.contentstack.com/scim/v2.0/endpoint.
SCIM API supports GET/POST/PUT/DELETE/PATCH verbs or methods.
URL paths are written in lower case.
Query parameters use the Camel case style.
The success/failure status of an operation is determined by the HTTP status it returns. Additional information is included in the HTTP response body.
The JSON number type is bound to a signed 32-bit integer.

Rate limiting

Rate limit is the maximum number of requests you can make using Contentstack’s API in a given time period.

By default, the Contentstack SCIM API enforces the following rate limits:

Read (GET) requests: 25 requests per second per organization
Write (POST/PUT/DELETE) requests: 25 requests per second per organization

Your application will receive the HTTP 429 response code if the requests for a given time period exceed the defined rate limits.

We also have set a limit on stack creation. Organizations can create only one stack per minute.

The aforementioned limits are configurable depending on your plan. For more information, contact our Support team.

To get the current rate limit status, you can check the returned HTTP headers of any API request. These rate limits are reset at the start of each time period.

Headers	Description
X-RateLimit-Limit	The maximum number of request a client is allowed to make per second per organization.
X-RateLimit-Remaining	The number of requests remaining in the current time period.

Errors

If there is something wrong with the API request, Contentstack returns an error.

Contentstack supports SCIM implementation that uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error.

Let’s look at the error code and their meanings.

HTTP status code	Description
`400 Bad Request`	The request is unparsable, syntactically incorrect, or violates schema.
`401 Unauthorized`	The authorization header is invalid or missing.
`403 Forbidden`	Operation is not permitted based on the provided authorization.
`404 Not Found`	The requested resource (for example, User) or endpoint does not exist.
`409 (Conflict)`	The service provider refused to create a new or duplicate resource.
`412 Pre Condition Failed`	Failed to update.
`429 Rate Limit Exceeded`	The number of requests exceeds the allowed limit for the given time period.
`500 Internal Server Error`	The server is malfunctioning and is not specific on what the problem is.
`501 Not Implemented`	The requested operation is not supported

API Reference

Users

Use the SCIM API requests to provision, deprovison, and perform other operations on users.

Provision Users into Organization

Provision User into Organization

Try

The Provision User into Organization request adds the user to a Contentstack organization.

If the user does not already exist in Contentstack, you can add the new user to the organization by using this request.

Get All Users

Try

The Get All Users request fetches the list of all users (along with details such as name, user ID, and email address) of your Contentstack organization.

Get Single User By ID

Try

The Get Single User by ID request returns comprehensive information of a specific user that exists in the organization.

You need to pass the ID of the user as the URL parameter.

Get Single User By Username

Try

The Get Single User by Username request returns comprehensive details of a specific user that exists in the Contentstack organization.

You need to pass the username as a query parameter.

Update User By ID (PUT)

Try

The Update User Using PUT request lets you update the details of a specific user by using the PUT request type.

In the “Body” section, you need to provide the updated schema of the user in the JSON format.

Note: As no user attributes are liable to change, this endpoint is currently provided for identity provider compatibility. Set the active flag to “False” to deprovision a user.

Update User By ID (PATCH)

Try

The Update User Using PATCH request lets you update the details of a specific user by using the PATCH request type.

In the “Body” section, you need to provide the updated schema of the user in JSON format.

Note: As no user attributes are liable to change, this endpoint is currently provided for identity provider compatibility. You can deprovision a user by sending the 'Replace' operation to the path 'active' with the value 'false'.

Deprovision User

Try

The Deprovision User request lets you remove a user from a Contentstack organization.

This will remove the user from all the assigned stacks, but the user will continue to have a Contentstack account.

Groups

Use the SCIM API requests to create groups, manage users within it, and perform other operations on groups.

Create Group

Try

The Create Group request lets you create a group in your IdP client and add users to it.

In the "Request Body" section, you need to pass the ID of the user in Contentstack as the value. Refer to the Get All Users request to get the user ID. Also, provide a name to the group in the displayName key.

Get All Groups

Try

The Get All Groups request fetches details of all groups that exist in the IdP client account.

Get Single Group By ID

Try

The Get Single Group by ID request fetches details of a single group that exists in the IdP client account.

Get Single Group By Display Name

Try

The Get Single Group By Display Name returns comprehensive details of a specific group that exists in the IdP client account, which is mapped in your Contentstack organization.

You need to pass the displayname as a query parameter.

Add Users to Group

Try

The Add Users to Group request adds the user(s) to a group.

The specified user will then have the permissions (at the stack level and at the organization level) that are specific to that group.

In the "Request Body", you need to pass the ID of the user in the value key.

Rename Group

Try

The Rename Group request lets you change the name of a group.

In the "Request Body", you need to pass a new name for the group in the value key.

Remove All Users from Group

Try

The Remove All Users from Group request removes all the existing users from a group.

This also revokes admin access for users with admin roles, unless those users have been assigned the admin role by some other group. The same logic applies to stack roles as well.

Remove User from Group

Try

The Remove User from Group request removes a user from a group.

In the "Request Body", you need to pass the ID of the user you want to remove from the group. Refer to the Get All Users request to get the ID.

This also revokes admin access for the user with an admin role, unless that user has been assigned an admin role by some other group as well. The same logic applies to stack roles as well.

Replace Users in Group

Try

The Replace Users in Group request replaces the existing set of users with a new set of users.

In the "Request Body", pass the user ID in the value key. Refer to the Get All Users request to get the user IDs.

This request removes all the existing users from a group and replaces them with the specified user(s).

This also revokes admin access for users with admin role, unless that user has been assigned an admin role by some other group as well. The same logic applies to stack roles as well.

Delete Group

Try

The Delete Group request deletes an existing group from the SCIM. This will remove all the users from that group.

Note: This API request will not remove users from the organization or from the Contentstack account.

Schema Discovery

Use the SCIM API requests to retrieve information about SCIM schemas supported by Contentstack and types of available resources.

Get Schemas

Try

The Get Schemas request fetches a list of schemas for all supported resources, which can be used to introspect resources and attribute extensions

Get Resource Types

Try

The Get Resource Types request returns the list of available resource types like Users or Groups.

Was this article helpful?

Thanks for your feedback

System for Cross-domain Identity Management (SCIM)Beta