# 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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | 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

<mark style="color:blue;">`GET`</mark> `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

<mark style="color:blue;">`GET`</mark> `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

<mark style="color:orange;">`PUT`</mark> `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

<mark style="color:red;">`DELETE`</mark> `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.

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

{% tabs %}
{% tab title="200: OK" %}

```javascript
{
  "success": true
}
```

{% endtab %}
{% endtabs %}

## Add Group Members

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | 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

<mark style="color:red;">`DELETE`</mark> `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

<mark style="color:blue;">`GET`</mark> `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

<mark style="color:blue;">`GET`</mark> `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

<mark style="color:green;">`POST`</mark> `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

<mark style="color:blue;">`GET`</mark> `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: 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:

```
GET https://docs.appmixer.com/api/user-groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.