--- title: "Administration API" description: "Explore Administrations APIs to manage organization user session, users, roles, audit logs, teams and SCIM operations." url: "https://www.contentstack.com/docs/developers/apis/administration-api" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-04-08" --- # Administration API ## Introduction ### Base URL * AWS North America (AWS NA): https://api.contentstack.io * AWS Europe (EU): https://eu-api.contentstack.com * AWS Australia (AWS AU): https://au-api.contentstack.com * Azure North America (Azure NA): https://azure-na-api.contentstack.com * Azure Europe (Azure EU): https://azure-eu-api.contentstack.com * GCP North America (GCP NA): https://gcp-na-api.contentstack.com * GCP Europe (GCP EU): https://gcp-eu-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](https://www.contentstack.com) or refer to our [documentation site](https://www.contentstack.com/docs) to understand what we do. The Administration APIs are used to manage your Contentstack organization. ### Content Management SDKs We have created SDKs, API references, getting started guides, and [sample apps](/docs/developers/sample-apps) for some of the popular languages and platforms. You can use them to build your own apps and manage your content from Contentstack. Contentstack Management SDKs interact with the Administration APIs and allow you to manage your organization settings. They are read-write in nature. You will find a list of all the available management SDKs under the [Content Management SDKs](/docs/developers/sdks/) section. We provide Management SDKs for the following platform: * [JavaScript](/docs/developers/sdks/content-management-sdk/javascript/) * [.NET](/docs/developers/sdks/content-management-sdk/dot-net/) * [Java](/docs/developers/sdks/content-management-sdk/java/) * [Python](/docs/developers/sdks/content-management-sdk/python/) ### Authentication Contentstack uses the authtoken or OAuth token, API key, and Organization ID to make Administration API requests. #### How to Get Authtoken Authtokens are user-specific tokens generated when user logs in to Contentstack. To retrieve the authtoken, log in to your Contentstack account by using the "[Log in to your account](/docs/developers/apis/administration-api#logging-in-out)" request. This request will return the authtoken in the response body. You can generate multiple authtokens by executing the "Log in to your account" request multiple times. These tokens do not have an expiration time limit. However, currently, there is a maximum limit of **20** valid tokens that a user can use per account at a time, to execute CMA requests. If you already have valid 20 tokens, creating a new authtoken will automatically cause the oldest authtoken to expire without warning. For SSO-enabled organizations, the "Log in to your account" request will not return the user authtoken for users who access the organization through Identity Provider login credentials. Consequently, any requests that require user authtoken will not work. Only the owner of the organization and users with permission to access the organization without SSO can use the Content Management APIs. Learn more about [REST API Usage](/docs/developers/single-sign-on/rest-api-usage). **Tip**: An alternate way to retrieve the authtoken is via **Inspect** element. If you are logged in through your browser, right-click and select **Inspect** or press “F12” to open developer tools, and select the **Network** tab. #### M2M OAuth Token **Machine-to-Machine** (**M2M**) apps are designed for secure server-to-server communication, eliminating the need for user intervention. These apps use the OAuth 2.0 protocol for authentication and authorization, making them highly secure and reliable for machine-to-machine interactions. Refer to our guide on [Machine-to-Machine Apps](/docs/developers/developer-hub/machine-to-machine-apps) for more information. **Note**: The M2M app is currently in Beta. Reach out to our [support](mailto:support@contentstack.com) team to enable it for your organization. #### How to Get Organization ID To retrieve the Organization ID, perform the steps given below: 1. Select the Organization from the dropdown on the header and click the “Org Admin” icon in the left navigation panel. Or, you can simply click the “Org Admin” cog beside the Organization that you intend to open. 2. Click the **Info** tab to access the section. **Note**: Only organization [Owner](/docs/developers/organization/organization-roles#organization-owner) and [Admin](/docs/developers/organization/organization-roles#organization-admin) roles can view the Organization ID. ### 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 enforces the following rate limits: * **Read (GET) requests**: 10 requests per second per organization. * **Write (POST/PUT/DELETE) requests**: 10 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. **Note**: Bulk actions do not follow the standard CMA rate limit of 10 requests per second. The default rate limit for bulk actions is **1 request per second** i.e., in one second you can make only one bulk action API request. 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](mailto:support@contentstack.com) 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. ### API conventions * The base URL for Analytics API for different regions can be found in the [Base URL](#base-url) section. * URL paths are written in lower case. * Query parameters and JSON fields use lower case, with underscores (\_) separating words. * 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 bounded to a signed 32-bit integer. ### Errors If there is something wrong with the API request, Contentstack returns an error. Contentstack uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error. In general, codes in the 2xx range signify success. The codes in the 4xx range indicate error, mainly due to information provided (for example, a required parameter or field was omitted). Lastly, codes in the 5xx range mean that there is something wrong with Contentstack’s servers; it is very rare though. Let’s look at the error code and their meanings. HTTP status code Description 400 Bad Request The request was incorrect or corrupted. 401 Access Denied The login credentials are invalid. 403 Forbidden Error The page or resource that is being accessed is forbidden. 404 Not Found The requested page or resource could not be found. 412 Pre Condition Failed The entered API key is invalid. 422\* Unprocessable Entity (also includes Validation Error and Unknown Field) The request is syntactically correct but contains semantic errors. 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. 502 Bad Gateway Error A server received an invalid response from another server. 504 Gateway Timeout Error A server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser. **\*** Contentstack returns the **422** HTTP status code with the "UID is not valid" message when an entry doesn’t exist, has been deleted, or belongs to a different content type. To check if an entry has been deleted, first try retrieving it from the CDN, then from the origin server if needed. This error can also occur due to invalid query parameters, such as using an empty array with logical operators like $and. Always ensure your queries contain valid conditions. For example, {"$and": \[{}, {}\]} is not a valid query. **Note**: The error codes that we get in the JSON response are not HTTP error codes but are custom Contentstack error codes that are used for internal purposes. ## API Reference ### User Session User session consists of calls that will help you to sign in and sign out of your Contentstack account. #### Logging in/out The Log in to your account request is used to sign in to your Contentstack account and obtain the authtoken. **Note:** The authtoken is a mandatory parameter when executing Content Management API calls. However, when executing Content Delivery API calls, use [the Content Delivery base URL](/docs/developers/apis/content-delivery-api/) for your region, and pass the environment-specific delivery token against the access\_token key. In the 'Body' section, enter the user credentials in JSON format. The JSON query will include the email address, the Contentstack user account password, and the two-factor authentication token (if enabled) received in the Authy app or SMS. For SSO-enabled organizations, the ‘Log in to your account’ request will not return the user authtoken for users. In this case, you can try out the following: * The owner of an organization can access the SSO-enabled organization through Contentstack credentials and retrieve the user authtoken to make Content Management API requests. * Disable 'Strict Mode' for an SSO-enabled organization, and users who have the ability to access their organization through Contentstack credentials can retrieve the authtoken to make Content Management API requests. For more details, refer the [REST API Usage - Content Management API](/docs/developers/single-sign-on/rest-api-usage#content-management-api) section in the Single Sign-On page. The Log out of your account call is used to sign out the user of Contentstack account. ### Users All accounts registered with Contentstack are known as [Users](/docs/developers/invite-users-and-assign-roles/about-stack-users). A [stack](/docs/developers/set-up-stack/about-stack) can have many users with varying permissions and roles.  **Note:** Before executing any calls, retrieve the authtoken by authenticating yourself via the Log in call of User Session. The authtoken is returned in the 'Response' body of the Log in call and is mandatory in all of the calls. Example: blt3cecf75b33bb2ebe #### Get User The Get user call returns comprehensive information of an existing user account. The information returned includes details of the stacks owned by and shared with the specified user account. #### Update User The Update User API Request updates the details of an existing user account. Only the information entered here will be updated, the existing data will remain unaffected. When executing the API call, under the 'Body' section, enter the information of the user that you wish to update. This information should be in JSON format. **Additional Resource:** To update the role of an existing user, refer to the [Update Existing User Role](#update-existing-user-role) API Request. #### Activate User The Activate a user account call activates the account of a user after signing up. For account activation, you will require the token received in the activation email. #### Request Password The Request for a password API helps to get a temporary password to log into an account in case a user has forgotten the login password. Using this temporary password, you can log in to your account and [set a new password](/docs/developers/password-related-security/forgot-reset-password) for your Contentstack account. In the 'Body' section, provide the user's email address in JSON format. **Note:** The “**Reset password**” token that you receive in your email address is valid only for the **next 60 minutes** after it’s generated. Post that, it expires and you need to rerun the [Reset password](/docs/developers/apis/content-management-api/#reset-password) API request to generate a new token. #### Reset Password The Reset password API request allows you to reset your Contentstack account password. **Note:** Before using this API request, you need to execute the [Request for a password](/docs/developers/apis/content-management-api/#request-for-a-password) API request to receive the reset password token in your registered email address. When executing the request, in the 'Body' section, you need to provide the token that you receive via email, your new password, and password confirmation in JSON format. **Note**: The "**Reset password**" token is valid only for the **next 60 minutes** after it’s generated. Post that, it expires and you need to rerun the same request to generate a new token. ### Organizations [Organization](/docs/owners-and-admins/about-organizations) is the top-level entity in the hierarchy of Contentstack, consisting of [stacks](/docs/developers/set-up-stack/about-stack) and stack resources, and users. Organization allows easy management of projects as well as users within the Organization. #### Get All Organizations The Get all organizations call lists all organizations related to the system user in the order that they were created. #### Get Single Organization The Get a single organization call gets the comprehensive details of a specific organization related to the system user. #### Organization Roles The Get all roles in an organization call gives the details of all the roles that are set to users in an Organization. When executing the API call, provide the Organization's UID. #### Organization Users The Get Organization users by email request retrieves information about users within an organization based on their email addresses. When executing the API request, you need to provide the organization UID. In the request body, you need to enter the email IDs of the users whose details you want to retrieve from the mentioned organization, like as follows: ``` { "emails":["abc@sample.com", "xyz@sample.com", …]} ``` **Note:** If you do not pass the request body, you will get the details of all the users in the Organization. The Add users to organization request allows you to send invitations to add users to your organization. Only the owner or the admin of the organization can add users. When executing the API request, in the request body, provide the organization admin/member role ID, obtained from the Get all roles in an Organization request. Also, provide the stack role UID of the user in the request body, obtained from the Get all roles request. The Remove users from organization request allows you to remove existing users from your organization. **Note**: Only the owner or the admin of the organization can remove users. When executing the API request, provide the organization UID. In the “Body” section, you need to enter the email IDs of the users you want to remove from the organization as follows: ``` { "emails":[ "abc@sample.com", "xyz@sample.com" ] } ``` The Resend pending organization invitation request allows you to resend the Organization invitations to users who have not yet accepted the earlier invitation. Only the owner or the admin of the Organization can resend the invitation to add users to an Organization. When executing Get all organization invitations request, you get the invitation status that helps to identify the pending invitations and share UID. When executing the Resend pending organization invitation API request, provide the Organization UID and share UID. The Get all organization invitations call gives you a list of all the Organization invitations. Only the owner or the admin of the Organization can resend the invitation to add users to an Organization. When executing the API call, provide the Organization UID. #### Transfer Organization Ownership The Transfer organization ownership call transfers the ownership of an Organization to another user. When the call is executed, an email invitation for accepting the ownership of a particular Organization is sent to the specified user. Once the specified user accepts the invitation by clicking on the link provided in the email, the ownership of the Organization gets transferred to the new user. Subsequently, the previous owner will no longer have any permission on the Organization. When executing the API call, provide the Organization UID. #### Organization Stacks The Get all stacks in an organization call fetches the list of all stacks in an Organization. When executing the API call, provide the Organization UID. #### Organization Logs The Get organization log details request is used to retrieve the audit log details of an organization. You can apply queries to filter the results. Refer to the [Queries](/docs/developers/apis/content-delivery-api#queries) section for more details. When executing the API call, provide the Organization UID. **Tip**: This request returns only the first **25 audit log items** of the specified organization. If you get more than **25 items** in your response, refer to the [Pagination](/docs/developers/apis/content-delivery-api#pagination) section to retrieve all the log items in a paginated form. The Get organization log item request is used to retrieve a specific item from the audit log of an organization. When executing the Get organization log details request, you get the Organization UID and Log UID. Use these values to execute the Get organization log item API request. ### Teams Teams, simplifies role and permission management by grouping users. Instead of assigning roles individually or at the stack level, you can directly assign roles to a team. This ensures that all team members share the same set of role permissions. #### Get all teams The Get all teams request returns comprehensive information of all the teams available in your organization. #### Get a single team The Get a single team request returns comprehensive information of a specific team available in a particular organization. #### Create a team The Create a team request creates a team in the specified organization. #### Update a team The Update a team request is used to modify details, such as adding or removing users from a team, assigning or removing stack roles within a team, updating team descriptions, and updating organization roles for an existing team within a specific organization. #### Delete a team The Delete a team request deletes an existing team along with all its associated users and assigned roles. #### Users All accounts registered with Contentstack are known as [Users](/docs/developers/invite-users-and-assign-roles/about-stack-users). An organization can have many users with varying permissions and roles. ##### Get all users of team The Get all users of team request retrieves information about all the users associated with a particular team. Additionally, you can also set the query parameters: includeUserDetails or include\_count to true to include user details and the count of users in the response. ##### Add users to team The Add users to team request allows you to send invitations to add users and assign them organizational and stack roles. **Note**: Only the Owner or the Admin of the organization can add users to a team. You need to pass the email IDs of the users in the request body as follows: ``` { "emails": [ "user1@contentstack.com", "user2@contentstack.com"]} ``` ##### Remove a user from team The Remove a user from team request allows you to remove an existing user from a particular team. **Note**: Only the Owner or the Admin of the organization can remove users from a team. #### Stack Role Mapping When adding users to a team, you have the option to simultaneously assign roles for the available stacks within the organization. This process involves mapping stack roles for all the users added to the team. ##### Get all stack role mapping The Get all stack role mapping request allows you to retrieve details of all associated stacks for a specified team in your organization. ##### Add a stack role mapping The Add a stack role mapping request allows you to associate users from a specified team with the available stacks in your organization. You need to pass the API key of the stack and the role UIDs in the request body as follows: ``` { "stackApiKey": "stack_api_key", "roles": [ "role_one_uid", "role_two_uid" ]} ``` ##### Update a stack role mapping The Update a stack role mapping request allows you to update the stack roles for a specific stack in your organization. You need to pass the role UIDs in the request body as follows: ``` { "roles": [ "role_uid" ]} ``` ##### Remove a stack role mapping The Remove a stack role mapping request allows you to delete the associations of team users for a specified stack in your organization.