> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/6.0/6.5/api/user-groups.md). # User Groups User Groups (also known as Workspaces) enable teams to collaborate by sharing resources such as flows, data stores, and files. All resources are owned by the group rather than individual users, while maintaining audit trails for individual user actions. ## Overview * All group resources are shared among group members * Individual user actions are tracked in audit logs * Admin users are automatically added to the "admin" user group * Users can switch between personal and group contexts * JWT tokens include group information for proper authorization ## Create User Group `POST` `https://api.YOUR_TENANT.appmixer.cloud/user-groups` Create a new user group. Admin token required. ```bash curl -XPOST "https://api.appmixer.com/user-groups" \ -H "Authorization: Bearer [ADMIN_TOKEN]" \ -H "Content-type: application/json" \ -d '{ "name": "Marketing Team", "metadata": { "department": "marketing" } }' ``` #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | ------------------------------- | | name\* | string | Name of the user group | | metadata | object | Optional metadata for the group | {% tabs %} {% tab title="201: Created" %} ```javascript { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing Team", "userId": "group-1678901234567", "metadata": { "department": "marketing" }, "created": 1678901234567, "members": [] } ``` {% endtab %} {% endtabs %} ## List User Groups `GET` `https://api.YOUR_TENANT.appmixer.cloud/user-groups` List all user groups. Admin users see all groups, regular users see only their own groups. ```bash curl -XGET "https://api.appmixer.com/user-groups" \ -H "Authorization: Bearer [ACCESS_TOKEN]" ``` {% tabs %} {% tab title="200: OK" %} ```javascript [ { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing Team", "userId": "group-1678901234567", "metadata": { "department": "marketing" }, "created": 1678901234567, "members": ["user1", "user2"] }, { "id": "5f8a7b2c3d4e5f6a7b8c9d0f", "name": "Admin Group", "userId": "group-1678901234568", "metadata": {}, "created": 1678901234568, "members": ["admin1"] } ] ``` {% endtab %} {% endtabs %} ## Get User Group `GET` `https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId` Get details of a specific user group. Users can only access groups they belong to, admins can access all groups. ```bash curl -XGET "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e" \ -H "Authorization: Bearer [ACCESS_TOKEN]" ``` {% tabs %} {% tab title="200: OK" %} ```javascript { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing Team", "userId": "group-1678901234567", "metadata": { "department": "marketing" }, "created": 1678901234567, "members": ["user1", "user2", "user3"] } ``` {% endtab %} {% endtabs %} ## Update User Group `PUT` `https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId` Update user group details. Admin token required. ```bash curl -XPUT "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e" \ -H "Authorization: Bearer [ADMIN_TOKEN]" \ -H "Content-type: application/json" \ -d '{ "name": "Marketing & Sales Team", "metadata": { "department": "marketing", "region": "EMEA" } }' ``` #### Request Body | Name | Type | Description | | -------- | ------ | ------------------------------------ | | name | string | Updated name of the group | | metadata | object | Updated metadata (replaces existing) | {% tabs %} {% tab title="200: OK" %} ```javascript { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing & Sales Team", "userId": "group-1678901234567", "metadata": { "department": "marketing", "region": "EMEA" }, "created": 1678901234567 } ``` {% endtab %} {% endtabs %} ## Delete User Group `DELETE` `https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId` Delete a user group. Admin token required. This will remove the group and revoke all group member access to shared resources. Deleting a group that still owns flows is rejected with a `400` error — transfer the group's resources first (see [Transfer Resources](#transfer-resources)), or pass `?force=true` to delete the group together with all its resources. ```bash curl -XDELETE "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e" \ -H "Authorization: Bearer [ADMIN_TOKEN]" ``` #### Query Parameters | Name | Type | Description | | ----- | ------- | ------------------------------------------------------------------------------------ | | force | boolean | Delete the group even if it still owns resources; all its resources are removed too. | {% tabs %} {% tab title="200: OK" %} ```javascript { "success": true } ``` {% endtab %} {% endtabs %} ## Transfer Resources `PUT` `https://api.YOUR_TENANT.appmixer.cloud/resources/transfer` Transfer **all resources** (flows, accounts, access tokens, flow versions, data stores, files, telemetry, ...) from a user or group to another user or group. Admin token required. Typical use cases: an employee leaving (transfer their resources to a group or a colleague), or consolidating group ownership. The transfer runs as a background task — the endpoint returns `202 Accepted` with a `ticket`. The source user is blocked (`metadata.blocked`) before the transfer starts to prevent API access during the migration; requesting a transfer for an already-blocked source returns `409 Conflict`. Running flows keep running during and after the transfer. ```bash curl -XPUT "https://api.appmixer.com/resources/transfer" \ -H "Authorization: Bearer [ADMIN_TOKEN]" \ -H "Content-type: application/json" \ -d '{ "sourceUserId": "5f8a7b2c3d4e5f6a7b8c9d0e", "targetGroupId": "64b0a1c2d3e4f5a6b7c8d9e0" }' ``` #### Request Body Provide exactly one of `sourceUserId`/`sourceGroupId` and exactly one of `targetUserId`/`targetGroupId`. | Name | Type | Description | | ------------- | ------ | --------------------------------- | | sourceUserId | string | User to transfer resources from. | | sourceGroupId | string | Group to transfer resources from. | | targetUserId | string | User to transfer resources to. | | targetGroupId | string | Group to transfer resources to. | {% tabs %} {% tab title="202: Transfer started" %} ```javascript { "ticket": "2e9dd726-2b7f-46f7-bea4-8db7f7175aa8" } ``` {% endtab %} {% tab title="409: Transfer already in progress" %} ```javascript { "error": "A transfer for this source is already in progress or has been completed" } ``` {% endtab %} {% endtabs %} ## Add Group Members `POST` `https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId/members` Add one or more members to a user group. Admin token required. ```bash curl -XPOST "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e/members" \ -H "Authorization: Bearer [ADMIN_TOKEN]" \ -H "Content-type: application/json" \ -d '{ "userIds": ["user1", "user2", "user3"] }' ``` #### Request Body | Name | Type | Description | | ----------------------------------------- | --------- | ------------------------ | | userIds\* | string\[] | Array of user IDs to add | {% tabs %} {% tab title="200: OK" %} ```javascript { "added": ["user1", "user2", "user3"], "group": { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing Team", "members": ["user1", "user2", "user3"] } } ``` {% endtab %} {% endtabs %} ## Remove Group Member `DELETE` `https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId/members/:userId` Remove a member from a user group. Admin token required. This will revoke all issued tokens for the removed user in this group context. ```bash curl -XDELETE "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e/members/user1" \ -H "Authorization: Bearer [ADMIN_TOKEN]" ``` {% tabs %} {% tab title="200: OK" %} ```javascript { "success": true, "removedUserId": "user1", "revokedTokens": 3 } ``` {% endtab %} {% endtabs %} ## Get Group Members `GET` `https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId/members` Get all members of a user group. Users can only access groups they belong to, admins can access all groups. ```bash curl -XGET "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e/members" \ -H "Authorization: Bearer [ACCESS_TOKEN]" ``` {% tabs %} {% tab title="200: OK" %} ```javascript { "members": [ { "id": "user1", "username": "john@example.com", "email": "john@example.com" }, { "id": "user2", "username": "jane@example.com", "email": "jane@example.com" } ] } ``` {% endtab %} {% endtabs %} ## List User's Groups `GET` `https://api.YOUR_TENANT.appmixer.cloud/users/:userId/groups` Get all groups that a specific user belongs to. ```bash curl -XGET "https://api.appmixer.com/users/user1/groups" \ -H "Authorization: Bearer [ACCESS_TOKEN]" ``` {% tabs %} {% tab title="200: OK" %} ```javascript { "groups": [ { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing Team", "userId": "group-1678901234567", "metadata": { "department": "marketing" } }, { "id": "5f8a7b2c3d4e5f6a7b8c9d0f", "name": "Admin Group", "userId": "group-1678901234568", "metadata": {} } ] } ``` {% endtab %} {% endtabs %} ## Switch Context `POST` `https://api.YOUR_TENANT.appmixer.cloud/auth/switch-context` Switch user context between personal workspace and a group workspace. Returns a new JWT token with the selected context. ```bash curl -XPOST "https://api.appmixer.com/auth/switch-context" \ -H "Authorization: Bearer [ACCESS_TOKEN]" \ -H "Content-type: application/json" \ -d '{ "groupId": "5f8a7b2c3d4e5f6a7b8c9d0e" }' ``` #### Request Body | Name | Type | Description | | ------- | ------ | ----------------------------------------------------------------- | | groupId | string | Group ID to switch to, or null/omit to switch to personal context | {% tabs %} {% tab title="200: OK" %} ```javascript { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "context": { "type": "group", "groupId": "5f8a7b2c3d4e5f6a7b8c9d0e", "groupName": "Marketing Team", "originalUserId": "user1" }, "user": { "id": "group-1678901234567", "username": "group-1678901234567", "scope": ["user"], "type": "group" } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **JWT Token Structure with Groups** When operating in a group context, the JWT token includes: * `id`: The group user ID (resources are owned by this ID) * `originalUserId`: The actual user ID (for audit logging) * `groups`: Array of group IDs the user belongs to This ensures proper resource ownership while maintaining audit trails. {% endhint %} ## Get Available Contexts `GET` `https://api.YOUR_TENANT.appmixer.cloud/auth/available-contexts` List all available contexts (personal and groups) that the current user can switch to. ```bash curl -XGET "https://api.appmixer.com/auth/available-contexts" \ -H "Authorization: Bearer [ACCESS_TOKEN]" ``` {% tabs %} {% tab title="200: OK" %} ```javascript { "personal": { "type": "personal", "userId": "user1", "username": "john@example.com" }, "groups": [ { "id": "5f8a7b2c3d4e5f6a7b8c9d0e", "name": "Marketing Team", "userId": "group-1678901234567", "type": "group" }, { "id": "5f8a7b2c3d4e5f6a7b8c9d0f", "name": "Admin Group", "userId": "group-1678901234568", "type": "group" } ], "current": { "type": "personal", "userId": "user1" } } ``` {% endtab %} {% endtabs %} ## Use Cases ### Collaborative Teams User groups are ideal for teams that need to collaborate on integrations and automations: 1. **Create a group** for your team (e.g., "Marketing Team") 2. **Add team members** to the group 3. **Members switch context** to the group workspace 4. **All resources** (flows, accounts, data stores) are now shared among team members 5. **Audit logs** maintain individual user accountability ### Admin Group When a user is assigned the `admin` scope, they are automatically added to the default "Admin Group". This enables: * Shared access to all integration templates * Collaborative administration of the Appmixer instance * Shared ownership of admin-created resources ### SSO Integration User groups work with SSO (Single Sign-On) authentication: * JWT tokens from SSO providers should include a `groups` claim * Users are automatically assigned to groups based on the SSO groups claim * Tokens are refreshed correctly to maintain group membership ## Important Notes {% hint style="warning" %} **Token Revocation** When a user is removed from a group, all issued JWT tokens for that user in the group context are automatically revoked. However, if a token is being used inside a running flow component, it will continue to work until the component execution completes. {% endhint %} {% hint style="info" %} **Audit Trail** All actions performed by users in a group context are logged with the original user ID, ensuring full audit trail capability even when resources are shared. {% endhint %} {% hint style="info" %} **Resource Ownership** When operating in a group context: * All created resources (flows, accounts, data stores, files) are owned by the group user ID * All group members have equal access to these resources * Switching back to personal context shows only personally-owned resources {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.appmixer.com/6.0/6.5/api/user-groups.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.