Group Management API

RESTful API endpoints for managing groups, subgroups, and member relationships

All endpoints require authentication via Clerk session token. Include Authorization: Bearer <token> header in all requests.

List Groups

GET /api/groups

GET

Retrieve a paginated list of groups

Query Parameters

?page=1 - Page number (default: 1)

&search=engineering - Search by name or description

&limit=20 - Items per page (default: 20)

Example Request

GET /api/groups?page=1&search=engineering
Authorization: Bearer <clerk-session-token>

Example Response

{
  "success": true,
  "data": [
    {
      "id": "group_123",
      "name": "Engineering Team",
      "description": "All engineers",
      "slug": "engineering",
      "isActive": true,
      "memberCount": 25,
      "parentGroupId": null,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  }
}

Permissions Required

MASTER_ADMIN - View all groups

GROUP_ADMIN - View managed groups and subgroups

MEMBER - View groups they belong to

Get Group

GET /api/groups/:id

GET

Retrieve detailed information about a specific group

Path Parameters

:id - Group ID (string)

Example Response

{
  "success": true,
  "data": {
    "id": "group_123",
    "name": "Engineering Team",
    "description": "All engineers",
    "slug": "engineering",
    "isActive": true,
    "parentGroupId": null,
    "parentGroup": null,
    "subgroups": [
      {
        "id": "group_456",
        "name": "Frontend Team",
        "memberCount": 10
      }
    ],
    "members": [
      {
        "id": "user_789",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "role": "MEMBER"
      }
    ],
    "applications": [
      {
        "id": "app_101",
        "name": "Project Manager",
        "isActive": true
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-03-20T14:25:00Z"
  }
}

Create Group

POST /api/groups

POST

Create a new group or subgroup

Request Body

{
  "name": "Engineering Team",
  "description": "All engineers",  // Optional
  "slug": "engineering",
  "parentGroupId": "parent_id"  // Optional - for subgroups
}

Example Response

{
  "success": true,
  "data": {
    "id": "group_123",
    "name": "Engineering Team",
    "description": "All engineers",
    "slug": "engineering",
    "isActive": true,
    "parentGroupId": null,
    "createdAt": "2024-03-20T15:00:00Z"
  }
}

Permissions Required

MASTER_ADMIN - Create top-level groups

GROUP_ADMIN - Create subgroups under managed groups

Group slugs must be unique across the platform and can only contain lowercase letters, numbers, and hyphens.

Update Group

PATCH /api/groups/:id

PATCH

Update group details and settings

Request Body

{
  "name": "Updated Name",  // Optional
  "description": "New description",  // Optional
  "isActive": true  // Optional - activate/deactivate group
}

Example Response

{
  "success": true,
  "data": {
    "id": "group_123",
    "name": "Updated Name",
    "description": "New description",
    "slug": "engineering",
    "isActive": true,
    "updatedAt": "2024-03-20T15:30:00Z"
  }
}

Group slug cannot be changed after creation. All changes are audited with the actor and timestamp.

Delete Group

DELETE /api/groups/:id

DELETE

Soft delete a group (deactivation)

Example Response

{
  "success": true,
  "message": "Group deleted successfully",
  "data": {
    "id": "group_123",
    "isActive": false,
    "deletedAt": "2024-03-20T16:00:00Z"
  }
}

Groups are soft-deleted to preserve audit trails. Deleting a group will also remove all member associations but not delete the members themselves.

Permissions Required

MASTER_ADMIN - Delete any group

GROUP_ADMIN - Delete managed groups (not parent groups)

List Group Members

GET /api/groups/:id/members

GET

Retrieve all members of a specific group

Path Parameters

:id - Group ID (string)

Example Response

{
  "success": true,
  "data": [
    {
      "userId": "user_123",
      "groupId": "group_456",
      "role": "GROUP_ADMIN",  // GROUP_ADMIN | MEMBER
      "user": {
        "id": "user_123",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "imageUrl": "https://...",
        "isActive": true
      },
      "joinedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Add Group Member

POST /api/groups/:id/members

POST

Add a user to a group with a specific role

Request Body

{
  "userId": "user_123",
  "role": "MEMBER"  // GROUP_ADMIN | MEMBER
}

Example Response

{
  "success": true,
  "data": {
    "userId": "user_123",
    "groupId": "group_456",
    "role": "MEMBER",
    "joinedAt": "2024-03-20T15:00:00Z"
  }
}

Permissions Required

MASTER_ADMIN - Add members to any group

GROUP_ADMIN - Add members to managed groups

Update Member Role

PATCH /api/groups/:id/members/:userId

PATCH

Update a member's role within a group

Path Parameters

:id - Group ID (string)

:userId - User ID (string)

Request Body

{
  "role": "GROUP_ADMIN"  // GROUP_ADMIN | MEMBER
}

Example Response

{
  "success": true,
  "data": {
    "userId": "user_123",
    "groupId": "group_456",
    "role": "GROUP_ADMIN",
    "updatedAt": "2024-03-20T15:30:00Z"
  }
}

Role changes are audited. Only MASTER_ADMIN can assign GROUP_ADMIN role to top-level groups.

Remove Member

DELETE /api/groups/:id/members/:userId

DELETE

Remove a user from a group

Path Parameters

:id - Group ID (string)

:userId - User ID (string)

Example Response

{
  "success": true,
  "message": "Member removed successfully",
  "data": {
    "userId": "user_123",
    "groupId": "group_456",
    "removedAt": "2024-03-20T16:00:00Z"
  }
}

Removing a member also removes their access to group-specific applications unless they have individual user-specific access.

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid group slug format",
    "details": {
      "field": "slug",
      "value": "Invalid Slug!"
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired session token"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to manage this group"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Group not found"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "User is already a member of this group"
  }
}

Best Practices

• Use descriptive group names and slugs

• Create hierarchical subgroups for organization

• Validate slug format before creating groups

• Check member permissions before role changes

• Use pagination for large group lists

• Audit all member additions and removals

Don't

• Hard delete groups (use soft delete)

• Change group slugs after creation

• Create circular parent-child relationships

• Remove the last admin from a group

• Fetch all groups without pagination

• Skip permission checks for member operations

Group Management API

RESTful API endpoints for managing groups, subgroups, and member relationships

All endpoints require authentication via Clerk session token. Include Authorization: Bearer <token> header in all requests.

List Groups

GET /api/groups

GET

Retrieve a paginated list of groups

Query Parameters

?page=1 - Page number (default: 1)

&search=engineering - Search by name or description

&limit=20 - Items per page (default: 20)

Example Request

GET /api/groups?page=1&search=engineering
Authorization: Bearer <clerk-session-token>

Example Response

{
  "success": true,
  "data": [
    {
      "id": "group_123",
      "name": "Engineering Team",
      "description": "All engineers",
      "slug": "engineering",
      "isActive": true,
      "memberCount": 25,
      "parentGroupId": null,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  }
}

Permissions Required

MASTER_ADMIN - View all groups

GROUP_ADMIN - View managed groups and subgroups

MEMBER - View groups they belong to

Get Group

GET /api/groups/:id

GET

Retrieve detailed information about a specific group

Path Parameters

:id - Group ID (string)

Example Response

{
  "success": true,
  "data": {
    "id": "group_123",
    "name": "Engineering Team",
    "description": "All engineers",
    "slug": "engineering",
    "isActive": true,
    "parentGroupId": null,
    "parentGroup": null,
    "subgroups": [
      {
        "id": "group_456",
        "name": "Frontend Team",
        "memberCount": 10
      }
    ],
    "members": [
      {
        "id": "user_789",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "role": "MEMBER"
      }
    ],
    "applications": [
      {
        "id": "app_101",
        "name": "Project Manager",
        "isActive": true
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-03-20T14:25:00Z"
  }
}

Create Group

POST /api/groups

POST

Create a new group or subgroup

Request Body

{
  "name": "Engineering Team",
  "description": "All engineers",  // Optional
  "slug": "engineering",
  "parentGroupId": "parent_id"  // Optional - for subgroups
}

Example Response

{
  "success": true,
  "data": {
    "id": "group_123",
    "name": "Engineering Team",
    "description": "All engineers",
    "slug": "engineering",
    "isActive": true,
    "parentGroupId": null,
    "createdAt": "2024-03-20T15:00:00Z"
  }
}

Permissions Required

MASTER_ADMIN - Create top-level groups

GROUP_ADMIN - Create subgroups under managed groups

Group slugs must be unique across the platform and can only contain lowercase letters, numbers, and hyphens.

Update Group

PATCH /api/groups/:id

PATCH

Update group details and settings

Request Body

{
  "name": "Updated Name",  // Optional
  "description": "New description",  // Optional
  "isActive": true  // Optional - activate/deactivate group
}

Example Response

{
  "success": true,
  "data": {
    "id": "group_123",
    "name": "Updated Name",
    "description": "New description",
    "slug": "engineering",
    "isActive": true,
    "updatedAt": "2024-03-20T15:30:00Z"
  }
}

Group slug cannot be changed after creation. All changes are audited with the actor and timestamp.

Delete Group

DELETE /api/groups/:id

DELETE

Soft delete a group (deactivation)

Example Response

{
  "success": true,
  "message": "Group deleted successfully",
  "data": {
    "id": "group_123",
    "isActive": false,
    "deletedAt": "2024-03-20T16:00:00Z"
  }
}

Groups are soft-deleted to preserve audit trails. Deleting a group will also remove all member associations but not delete the members themselves.

Permissions Required

MASTER_ADMIN - Delete any group

GROUP_ADMIN - Delete managed groups (not parent groups)

List Group Members

GET /api/groups/:id/members

GET

Retrieve all members of a specific group

Path Parameters

:id - Group ID (string)

Example Response

{
  "success": true,
  "data": [
    {
      "userId": "user_123",
      "groupId": "group_456",
      "role": "GROUP_ADMIN",  // GROUP_ADMIN | MEMBER
      "user": {
        "id": "user_123",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "imageUrl": "https://...",
        "isActive": true
      },
      "joinedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Add Group Member

POST /api/groups/:id/members

POST

Add a user to a group with a specific role

Request Body

{
  "userId": "user_123",
  "role": "MEMBER"  // GROUP_ADMIN | MEMBER
}

Example Response

{
  "success": true,
  "data": {
    "userId": "user_123",
    "groupId": "group_456",
    "role": "MEMBER",
    "joinedAt": "2024-03-20T15:00:00Z"
  }
}

Permissions Required

MASTER_ADMIN - Add members to any group

GROUP_ADMIN - Add members to managed groups

Update Member Role

PATCH /api/groups/:id/members/:userId

PATCH

Update a member's role within a group

Path Parameters

:id - Group ID (string)

:userId - User ID (string)

Request Body

{
  "role": "GROUP_ADMIN"  // GROUP_ADMIN | MEMBER
}

Example Response

{
  "success": true,
  "data": {
    "userId": "user_123",
    "groupId": "group_456",
    "role": "GROUP_ADMIN",
    "updatedAt": "2024-03-20T15:30:00Z"
  }
}

Role changes are audited. Only MASTER_ADMIN can assign GROUP_ADMIN role to top-level groups.

Remove Member

DELETE /api/groups/:id/members/:userId

DELETE

Remove a user from a group

Path Parameters

:id - Group ID (string)

:userId - User ID (string)

Example Response

{
  "success": true,
  "message": "Member removed successfully",
  "data": {
    "userId": "user_123",
    "groupId": "group_456",
    "removedAt": "2024-03-20T16:00:00Z"
  }
}

Removing a member also removes their access to group-specific applications unless they have individual user-specific access.

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid group slug format",
    "details": {
      "field": "slug",
      "value": "Invalid Slug!"
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired session token"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to manage this group"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Group not found"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "User is already a member of this group"
  }
}

Best Practices

• Use descriptive group names and slugs

• Create hierarchical subgroups for organization

• Validate slug format before creating groups

• Check member permissions before role changes

• Use pagination for large group lists

• Audit all member additions and removals

Don't

• Hard delete groups (use soft delete)

• Change group slugs after creation

• Create circular parent-child relationships

• Remove the last admin from a group

• Fetch all groups without pagination

• Skip permission checks for member operations

Group Management API

List Groups

Query Parameters

Example Request

Example Response

Permissions Required

Get Group

Path Parameters

Example Response

Create Group

Request Body

Example Response

Permissions Required

Update Group

Request Body

Example Response

Delete Group

Example Response

Permissions Required

List Group Members

Path Parameters

Example Response

Add Group Member

Request Body

Example Response

Permissions Required

Update Member Role

Path Parameters

Request Body

Example Response

Remove Member

Path Parameters

Example Response

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

Best Practices

See Also

Group Management API

List Groups

Query Parameters

Example Request

Example Response

Permissions Required

Get Group

Path Parameters

Example Response

Create Group

Request Body

Example Response

Permissions Required

Update Group

Request Body

Example Response

Delete Group

Example Response

Permissions Required

List Group Members

Path Parameters

Example Response

Add Group Member

Request Body

Example Response

Permissions Required

Update Member Role

Path Parameters

Request Body

Example Response

Remove Member

Path Parameters

Example Response

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict