Skip to main content
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 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

​
username
string
required
Cognito username to add to the groupExample: [email protected]
​
groupName
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/[email protected]/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 groupExample: [email protected]
​
groupName
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/[email protected]/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: 
# Add to both admin and user groups
curl -X POST .../users/[email protected]/groups/admin
curl -X POST .../users/[email protected]/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/[email protected]/groups/admin
curl -X POST .../users/[email protected]/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": "[email protected]", ... }'

# Add to user group
curl -X POST /api/admin/users/[email protected]/groups/user

​
JWT Token Claims

Cognito encodes group membership in the JWT token: 
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us