User Groups

API for user groups (workspaces)

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.

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

201: Created

{
  "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
  "name": "Marketing Team",
  "userId": "group-1678901234567",
  "metadata": {
    "department": "marketing"
  },
  "created": 1678901234567,
  "members": []
}

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.

curl -XGET "https://api.appmixer.com/user-groups" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"

200: OK

[
  {
    "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"]
  }
]

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.

curl -XGET "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"

200: OK

{
  "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
  "name": "Marketing Team",
  "userId": "group-1678901234567",
  "metadata": {
    "department": "marketing"
  },
  "created": 1678901234567,
  "members": ["user1", "user2", "user3"]
}

Update User Group

PUT https://api.YOUR_TENANT.appmixer.cloud/user-groups/:groupId

Update user group details. Admin token required.

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)

200: OK

{
  "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
  "name": "Marketing & Sales Team",
  "userId": "group-1678901234567",
  "metadata": {
    "department": "marketing",
    "region": "EMEA"
  },
  "created": 1678901234567
}

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.

curl -XDELETE "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer [ADMIN_TOKEN]"

200: OK

{
  "success": true
}

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.

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

200: OK

{
  "added": ["user1", "user2", "user3"],
  "group": {
    "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
    "name": "Marketing Team",
    "members": ["user1", "user2", "user3"]
  }
}

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.

curl -XDELETE "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e/members/user1" \
  -H "Authorization: Bearer [ADMIN_TOKEN]"

200: OK

{
  "success": true,
  "removedUserId": "user1",
  "revokedTokens": 3
}

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.

curl -XGET "https://api.appmixer.com/user-groups/5f8a7b2c3d4e5f6a7b8c9d0e/members" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"

200: OK

{
  "members": [
    {
      "id": "user1",
      "username": "[email protected]",
      "email": "[email protected]"
    },
    {
      "id": "user2",
      "username": "[email protected]",
      "email": "[email protected]"
    }
  ]
}

List User's Groups

GET https://api.YOUR_TENANT.appmixer.cloud/users/:userId/groups

Get all groups that a specific user belongs to.

curl -XGET "https://api.appmixer.com/users/user1/groups" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"

200: OK

{
  "groups": [
    {
      "id": "5f8a7b2c3d4e5f6a7b8c9d0e",
      "name": "Marketing Team",
      "userId": "group-1678901234567",
      "metadata": {
        "department": "marketing"
      }
    },
    {
      "id": "5f8a7b2c3d4e5f6a7b8c9d0f",
      "name": "Admin Group",
      "userId": "group-1678901234568",
      "metadata": {}
    }
  ]
}

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.

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

200: OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "context": {
    "type": "group",
    "groupId": "5f8a7b2c3d4e5f6a7b8c9d0e",
    "groupName": "Marketing Team",
    "originalUserId": "user1"
  },
  "user": {
    "id": "group-1678901234567",
    "username": "group-1678901234567",
    "scope": ["user"],
    "type": "group"
  }
}

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.

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.

curl -XGET "https://api.appmixer.com/auth/available-contexts" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"

200: OK

{
  "personal": {
    "type": "personal",
    "userId": "user1",
    "username": "[email protected]"
  },
  "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"
  }
}

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

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.

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.

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