Group Management

Auto-generate your docs

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

object

array

Array of Cognito group objectsEach 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

curl -X GET https://api.example.com/api/admin/groups \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "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

string

required

Cognito username to add to the groupExample: user@example.com

string

required

Group name to add the user toValues: admin, user, viewer

Response

{
  "message": "User added to group 'admin' successfully."
}

Example Request

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

string

required

Cognito username to remove from the groupExample: user@example.com

string

required

Group name to remove the user fromValues: admin, user, viewer

Response

{
  "message": "User removed from group 'admin' successfully."
}

Example Request

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

error

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

error

Missing or invalid Bearer token

error

Forbidden — admin role required

error

User not found

Group Strategy

Multiple Groups

Users can belong to multiple groups simultaneously:

# 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:

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:

# 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:

{
  "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

Authentication

Assessments

Jobs

Prompts

Admin

Authentication

Available Groups

List Groups

Response

Example Request

Example Response

Add User to Group

Path Parameters

Response

Example Request

Permissions Impact

Remove User from Group

Path Parameters

Response

Example Request

Permissions Impact

Error Responses

Group Strategy

Multiple Groups

Group Hierarchy

Default Group

JWT Token Claims

Source Code

​Authentication

​Available Groups

​List Groups

​Response

​Example Request

​Example Response

​Add User to Group

​Path Parameters

​Response

​Example Request

​Permissions Impact

​Remove User from Group

​Path Parameters

​Response

​Example Request

​Permissions Impact

​Error Responses

​Group Strategy

​Multiple Groups

​Group Hierarchy

​Default Group

​JWT Token Claims

​Source Code

Authentication

Available Groups

List Groups

Response

Example Request

Example Response

Add User to Group

Path Parameters

Response

Example Request

Permissions Impact

Remove User from Group

Path Parameters

Response

Example Request

Permissions Impact

Error Responses

Group Strategy

Multiple Groups

Group Hierarchy

Default Group

JWT Token Claims

Source Code