--- title: "Administration | Teams" description: "

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.

" url: "https://www.contentstack.com/docs/developers/apis/administration-api/teams" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-06-24" --- # Administration | 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 ### Get all teams **GET** `/v4/teams` The Get all teams request returns comprehensive information about all the teams in your organization, so you can review how users are grouped and which organization roles, stack roles, and project roles each team carries. Contentstack identifies the organization from the organization\_uid request header and returns the teams that the requesting user can access. By default, the response is wrapped in a { count, teams } object and paginated, with x-total-results, x-skip, and x-limit returned as response headers. Use skip and limit to page through the results (default limit is 500), or set skip\_pagination to “true” to receive every team as a plain array without the wrapper. Refine the results with typeahead to match team names, user\_uid or stack\_api\_key to filter by membership or stack mapping, and asc or desc to sort. Set include\_user\_details to “true” to expand each team’s users array from UID strings into full user objects, and group\_roles\_by\_domain to “true” to add a rolesByDomain object that groups each team’s roles by domain. When the organization has no teams, the request returns a 204 response with no body. #### Query Parameters - **include_user_details** (optional) Set this parameter to “true” to include the details of users in the response. - **skip_pagination** (optional) Set this parameter to “true” to return all teams as a plain array, without the count and teams wrapper. - **typeahead** (optional) Retrieves responses that match the provided string. - **asc** (optional) Sort the response in ascending order. - **desc** (optional) Sort the response in descending order. - **limit** (optional) Enter the maximum number of teams to be returned. - **skip** (optional) Enter the number of teams to be skipped from the response body. - **user_uid** (optional) Enter the user UIDs in string format, separated by commas, for filtering. - **stack_api_key** (optional) Enter stack API keys in string format, separated by commas, to filter teams that have a role mapping for those stacks. - **group_roles_by_domain** (optional) Set this parameter to “true” to group each team's roles by domain in a rolesByDomain object. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **organization_uid** (required) Enter the UID of your Organization. Default: `your_organization_uid` #### Sample Response ```json { "count": 2, "teams": [ { "_id": "65b*****************e9a", "name": "Team A", "description": "Marketing team", "createdAt": "2024-02-01T09:55:46.703Z", "createdBy": "blt**************f0", "createdByUserName": "Jane Doe", "updatedAt": "2024-02-01T09:56:36.724Z", "updatedBy": "blt**************f0", "updatedByUserName": "Jane Doe", "organizationUid": "blt**************b5", "users": [ "blt**************a0", "blt**************8d" ], "organizationRoles": [ "blt**************8d" ], "stackRoleMapping": [ { "stackApiKey": "blt**************74", "roles": [ "blt**************37" ] } ], "projectRoles": [ { "projectUid": "blt**************p1", "domain": "am", "roles": [ "blt**************r1" ] } ], "__v": 0, "uid": "65b*****************e9a" }, { "_id": "65b*****************892", "name": "Sample Team", "createdAt": "2024-01-31T11:52:27.049Z", "createdBy": "blt**************f0", "createdByUserName": "Jane Doe", "updatedAt": "2024-01-31T11:52:27.049Z", "updatedBy": "blt**************f0", "updatedByUserName": "Jane Doe", "organizationUid": "blt**************b5", "users": [], "organizationRoles": [], "stackRoleMapping": [], "projectRoles": [], "__v": 0, "uid": "65b*****************892" } ] } ``` ## Get a single team ### Get a single team **GET** `/v4/teams/{team_uid}` The Get a single team request returns comprehensive information about one team in your organization, including its members and its assigned organization roles, stack role mappings, and project roles. Pass the team’s UID as team\_uid in the request path and your organization’s UID in the organization\_uid header. By default, the users array contains user UID strings. Set include\_user\_details to “true” to expand them into full user objects that include uid, username, email, firstName, lastName, active, and orgInvitationStatus. The uid and \_id fields hold the same value; use either to reference the team in follow-up requests. A request for a team that does not exist returns a 404 error. #### URL Parameters - **team_uid** (required) Enter the UID of the team of which you want to retrieve the details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Query Parameters - **include_user_details** (optional) Set this parameter to “true” to include the details of users in the response. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **organization_uid** (required) Enter the UID of your Organization. Default: `your_organization_uid` #### Sample Response ```json { "_id": "65b*****************e9a", "name": "Sample Team", "description": "Marketing team", "createdAt": "2024-02-01T09:55:46.703Z", "createdBy": "blt**************f0", "createdByUserName": "Sample User", "updatedAt": "2024-02-01T09:56:36.724Z", "updatedBy": "blt**************f0", "updatedByUserName": "Sample User", "organizationUid": "blt**************b5", "users": [ "blt**************a0", "blt**************8d" ], "organizationRoles": [ "blt**************8d" ], "stackRoleMapping": [ { "stackApiKey": "blt**************74", "roles": [ "blt**************37" ] } ], "projectRoles": [ { "projectUid": "blt**************p1", "domain": "am", "roles": [ "blt**************r1" ] } ], "__v": 0, "uid": "65b*****************e9a" } ``` ## Create a team ### Create a team **POST** `/v4/teams` The Create a team request creates a team in the specified organization and assigns its initial members and roles in a single call. Provide the team name (required) and, optionally, a description. Add members through the users array, where each entry identifies a user by email or uid. Grant access by including organizationRoles (organization-level role UIDs), stackRoleMapping (per-stack role assignments), and projectRoles (project-scoped roles; the am domain is currently supported). The users and stackRoleMapping arrays are required, but you can send them empty. On success, the request returns a 201 response with the created team, including its generated uid. The users array in the response contains UID strings; use the Get a single team request with include\_user\_details set to “true” to resolve full user objects. Invalid input, such as an unknown role or stack, returns a 400 error that identifies the failed field. #### Query Parameters - **include_user_details** (optional) Set this parameter to “true” to include the details of users in the response. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **organization_uid** (required) Enter the UID of your Organization. Default: `your_organization_uid` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "_id": "65b******************11", "name": "Team A", "description": "Marketing team", "createdAt": "2024-02-01T11:01:33.399Z", "createdBy": "blt**************f0", "createdByUserName": "Jane Doe", "updatedAt": "2024-02-01T11:01:33.399Z", "updatedBy": "blt**************f0", "updatedByUserName": "Jane Doe", "organizationUid": "blt**************b5", "users": [ "blt**************a0" ], "organizationRoles": [ "blt**************8d" ], "stackRoleMapping": [ { "stackApiKey": "blt**************74", "roles": [ "blt**************f6" ] } ], "projectRoles": [ { "projectUid": "blt**************p1", "domain": "am", "roles": [ "blt**************r1" ] } ], "__v": 0, "uid": "65b******************11" } ``` ## Update a team ### Update a team **PUT** `/v4/teams/{team_uid}` The Update a team request modifies an existing team, including its name, description, members, organization roles, stack role mappings, and project roles. This request replaces values rather than merging them. The users, organizationRoles, and stackRoleMapping values you send become the team’s complete set, so include every member and role you want to keep, not only the ones you are adding or changing. To clear one of these, send an empty array, for example "users": \[\]. The projectRoles field behaves differently: it stays unchanged only when you omit it entirely, and sending it with any value, including \[\], replaces the existing project roles. Pass the team’s UID as team\_uid in the request path and your organization’s UID in the organization\_uid header. On success, the request returns a 200 response with the updated team. Set include\_user\_details to “true” to receive full user objects in the response. #### URL Parameters - **team_uid** (required) Enter the UID of the team you want to update. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Query Parameters - **include_user_details** (optional) Set this parameter to “true” to include the details of users in the response. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **organization_uid** (required) Enter the UID of your Organization. Default: `your_organization_uid` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "_id": "65b*****************e9a", "name": "Team A", "description": "Marketing team", "createdAt": "2024-02-01T09:55:46.703Z", "createdBy": "blt**************f0", "createdByUserName": "Jane Doe", "updatedAt": "2024-02-01T11:06:35.107Z", "updatedBy": "blt**************f0", "updatedByUserName": "Jane Doe", "organizationUid": "blt**************b5", "users": [ "blt**************21" ], "organizationRoles": [ "blt**************8d" ], "stackRoleMapping": [ { "stackApiKey": "blt**************74", "roles": [ "blt**************f6" ] } ], "projectRoles": [ { "projectUid": "blt**************p1", "domain": "am", "roles": [ "blt**************r1" ] } ], "__v": 0, "uid": "65b*****************e9a" } ``` ## Delete a team ### Delete a team **DELETE** `/v4/teams/{team_uid}` The Delete a team request removes an existing team along with its members and assigned roles. Deletion is a soft delete: Contentstack marks the team as deleted and excludes it from subsequent reads instead of removing the record permanently. Deleting a team revokes the access that the team granted through its organization, stack, and project roles, unless a member holds the same access through another team or a direct assignment. Pass the team’s UID as team\_uid in the request path and your organization’s UID in the organization\_uid header. A successful request returns a 200 response, and deleting a team that does not exist returns a 404 error. #### URL Parameters - **team_uid** (required) Enter the UID of the team you want to delete. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **organization_uid** (required) Enter the UID of your Organization. Default: `your_organization_uid` ## 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 ### Get all users of team **GET** `/organizations/{organization_uid}/teams/{team_uid}/users` 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 #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Query Parameters - **includeUserDetails** (optional) Set this parameter to “true” to include the details of users in the response. - **include_count** (optional) Set this parameter to “true” to include the total count of users in the response. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` #### Sample Response ```json { "users": [ { "uid": "blt**************f0", "username": "jane_blt6266157b", "email": "jane.doer@contentstack.com", "firstName": "Jane", "lastName": "Doer", "active": true, "orgInvitationStatus": "accepted" }, { "uid": "blt**************8d", "username": "john_blt28057039", "email": "john.doe@contentstack.com", "firstName": "John", "lastName": "Doe", "active": true, "orgInvitationStatus": "accepted" }, { "uid": "blt**************21", "username": "jane_blt9d1e076e", "email": "jane.doe@contentstack.com", "firstName": "Jane", "lastName": "Doe", "active": true, "orgInvitationStatus": "accepted" }, { "uid": "blt**************a0", "username": "sample_blt03a1b0ad", "email": "sample.user@contentstack.com", "firstName": "Sample", "lastName": "User", "active": true, "orgInvitationStatus": "accepted" } ], "count": 4 } ``` ### Add users to team **POST** `/organizations/{organization_uid}/teams/{team_uid}/users` 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 #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` ### Remove a user from team **DELETE** `/organizations/{organization_uid}/teams/{team_uid}/users/{user_uid}` 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. - **user_uid** (required) Enter the UID of the user you want to remove from the team. The UID of a user is unique across an organization. Execute the [Get all users of team](/docs/developers/apis/content-management-api#get-all-users-of-team) request to retrieve the UID of a user. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` ## 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 ### Get all stack role mapping **GET** `/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappings` 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 #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` #### Sample Response ```json { "stackRoleMappings": [ { "stackApiKey": "blt**************74", "roles": [ "blt**************f6" ] }, { "stackApiKey": "blt**************fe", "roles": [ "blt**************3a" ] } ] } ``` ### Add a stack role mapping **POST** `/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappings` 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 #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "stackRoleMapping": { "stackApiKey": "blt**************74", "roles": [ "blt**************f6", "blt**************37" ] } } ``` ### Update a stack role mapping **POST** `/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappings/{stack_api_key}` 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 #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. - **stack_api_key** (required) Enter the API key of the stack. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "stackRoleMapping": { "stackApiKey": "blt**************74", "roles": [ "blt**************48", "blt**************f4" ] } } ``` ### Remove a stack role mapping **DELETE** `/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappings/{stack_api_key}` The Remove a stack role mapping request allows you to delete the associations of team users for a specified stack in your organization. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **team_uid** (required) Enter the UID of the team of which you want to retrieve the user details. The UID of a team is unique across an organization. Execute the [Get all teams](/docs/developers/apis/content-management-api#get-all-teams) request to retrieve the UID of a team. - **stack_api_key** (required) Enter the API key of the stack. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken`