> ## Documentation Index
> Fetch the complete documentation index at: https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Management

> Admin endpoints for managing Cognito user groups

The Group Management API allows admins to manage Cognito user groups and group membership. Groups control access levels and permissions.

## Authentication

All endpoints require JWT Bearer token (Cognito) with **admin role**.

## Available Groups

The system supports three groups:

* **`admin`** — Full admin access to all API endpoints
* **`user`** — Standard user access (can create and manage own assessments)
* **`viewer`** — Read-only access

***

## List Groups

**`GET /api/admin/groups`**

Returns all Cognito user groups defined in the user pool.

### Response

**data** `object`

**data.groups** `array`

Array of Cognito group objects

Each group has:

* `GroupName` (string): Group identifier (`admin`, `user`, or `viewer`)
* `Description` (string): Human-readable description
* `UserPoolId` (string): Cognito User Pool ID
* `CreationDate` (string): ISO 8601 timestamp
* `LastModifiedDate` (string): ISO 8601 timestamp

### Example Request

```bash theme={null}
curl -X GET https://api.example.com/api/admin/groups \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Example Response

```json theme={null}
{
  "data": {
    "groups": [
      {
        "GroupName": "admin",
        "Description": "Administrators with full access",
        "UserPoolId": "us-east-1_abc123",
        "CreationDate": "2026-01-15T10:00:00.000Z",
        "LastModifiedDate": "2026-01-15T10:00:00.000Z"
      },
      {
        "GroupName": "user",
        "Description": "Standard users",
        "UserPoolId": "us-east-1_abc123",
        "CreationDate": "2026-01-15T10:00:00.000Z",
        "LastModifiedDate": "2026-01-15T10:00:00.000Z"
      },
      {
        "GroupName": "viewer",
        "Description": "Read-only viewers",
        "UserPoolId": "us-east-1_abc123",
        "CreationDate": "2026-01-15T10:00:00.000Z",
        "LastModifiedDate": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}
```

***

## Add User to Group

**`POST /api/admin/users/:username/groups/:groupName`**

Adds a Cognito user to a group. Assigning the `admin` group grants full admin access to the API.

### Path Parameters

**username** `string` *required*

Cognito username to add to the group

**Example:** `user@example.com`

**groupName** `string` *required*

Group name to add the user to

**Values:** `admin`, `user`, `viewer`

### Response

```json theme={null}
{
  "message": "User added to group 'admin' successfully."
}
```

### Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/admin/users/user@example.com/groups/admin \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Permissions Impact

Adding a user to a group immediately grants them the associated permissions:

* **`admin`** — Can access all `/api/admin/*` endpoints, manage prompts, users, and groups
* **`user`** — Can create and manage their own assessments
* **`viewer`** — Can view assessments but cannot create or modify

Permissions take effect on the next token refresh (when the user logs in again or refreshes their token).

***

## Remove User from Group

**`DELETE /api/admin/users/:username/groups/:groupName`**

Removes a Cognito user from a group. Removing from the `admin` group revokes admin access immediately on the next token refresh.

### Path Parameters

**username** `string` *required*

Cognito username to remove from the group

**Example:** `user@example.com`

**groupName** `string` *required*

Group name to remove the user from

**Values:** `admin`, `user`, `viewer`

### Response

```json theme={null}
{
  "message": "User removed from group 'admin' successfully."
}
```

### Example Request

```bash theme={null}
curl -X DELETE https://api.example.com/api/admin/users/user@example.com/groups/admin \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Permissions Impact

Removing a user from a group revokes the associated permissions:

* If removed from **`admin`**, the user loses access to all admin endpoints
* If removed from **`user`**, the user cannot create new assessments
* If removed from **`viewer`**, the user loses read access

Permission changes take effect on the next token refresh.

***

## Error Responses

**400** `error`

Invalid group name (must be `admin`, `user`, or `viewer`)

**401** `error`

Missing or invalid Bearer token

**403** `error`

Forbidden — admin role required

**404** `error`

User not found

## Group Strategy

### Multiple Groups

Users can belong to multiple groups simultaneously:

```bash theme={null}
# Add to both admin and user groups
curl -X POST .../users/user@example.com/groups/admin
curl -X POST .../users/user@example.com/groups/user
```

The user will have the union of all group permissions.

### Group Hierarchy

There is no implicit hierarchy:

* `admin` does **not** automatically inherit `user` permissions
* You must explicitly add users to all relevant groups

**Recommendation:** Add admin users to both `admin` and `user` groups:

```bash theme={null}
curl -X POST .../users/admin@example.com/groups/admin
curl -X POST .../users/admin@example.com/groups/user
```

### Default Group

New users are **not** automatically added to any group. Admins must explicitly assign groups:

```bash theme={null}
# Create user
curl -X POST /api/admin/users -d '{ "email": "new@example.com", ... }'

# Add to user group
curl -X POST /api/admin/users/new@example.com/groups/user
```

## JWT Token Claims

Cognito encodes group membership in the JWT token:

```json theme={null}
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "cognito:groups": ["admin", "user"],
  "exp": 1709571200
}
```

The API's `AdminGuard` checks for the `admin` group in the `cognito:groups` claim.

## Source Code

Implementation: `packages/api/src/admin/groups.controller.ts`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.