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 [TENANT_API_URL]/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 [TENANT_API_URL]/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 [TENANT_API_URL]/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 [TENANT_API_URL]/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 [TENANT_API_URL]/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), or pass ?force=true to delete the group together with all its resources.

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.

200: OK

{
  "success": true
}

Transfer Resources

PUT [TENANT_API_URL]/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.

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.

202: Transfer started

{
  "ticket": "2e9dd726-2b7f-46f7-bea4-8db7f7175aa8"
}

409: Transfer already in progress

{
  "error": "A transfer for this source is already in progress or has been completed"
}

Add Group Members

POST [TENANT_API_URL]/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 [TENANT_API_URL]/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 [TENANT_API_URL]/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": "[e-mail]",
      "email": "[e-mail]"
    },
    {
      "id": "user2",
      "username": "[e-mail]",
      "email": "[e-mail]"
    }
  ]
}

List User's Groups

GET [TENANT_API_URL]/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 [TENANT_API_URL]/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 [TENANT_API_URL]/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": "[e-mail]"
  },
  "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