System for Cross-domain Identity Management (SCIM)BETA[API version: 2.0]
For US region: https://auth-api.contentstack.com
For European region: https://eu-auth-api.contentstack.com
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.
To use the SCIM API, you need to first authenticate yourself with your IdP client and generate its access token.
- 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 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.
|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.|
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
|400 Bad Request||
The request is unparsable, syntactically incorrect, or violates schema.
The authorization header is invalid or missing.
Operation is not permitted based on the provided authorization.
|404 Not Found||
The requested resource (for example, User) or endpoint does not exist.
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
Use the SCIM API requests to provision, deprovison, and perform other operations on users.
Provision Users into Organization
Get All Users
Get Single User By ID
Get Single User By Username
Update User By ID (PUT)
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, like name and email, 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)
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, like name and email, 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'.
Use the SCIM API requests to create groups, manage users within it, and perform other operations on groups.
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
Get Single Group By ID
Get Single Group By Display Name
Add Users to Group
Remove All Users from Group
Remove User from Group
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
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.
Use the SCIM API requests to retrieve information about SCIM schemas supported by Contentstack and types of available resources.