Home Documentation Authentication and User Management Service Integration Guides Users and Groups Management

Users and Groups Management

Last updated: January 2026

The Agglestone Authentication and User Management Service provides comprehensive REST APIs for managing users and groups in your tenant. These APIs allow you to create, read, update, and delete users and groups, organize users into groups for access control, and manage user settings.

What Are Users and Groups?

Users represent individuals who can authenticate and access your applications. Each user has an email address (required), an optional username, and various settings like password requirements, MFA settings, and group memberships.

Groups are collections of users that you can use for access control in your applications. When a user is added to a group, that group appears in their JWT token, allowing you to check group membership to control access to features, data, or functionality.

Authentication Requirements

All user and group management endpoints require either:

  • Admin privileges (users with the Admin group in their JWT token), or
  • API Key authentication (using the X-API-Key header)

This ensures that only authorized administrators can manage users and groups in your tenant.

Users

The Users API provides endpoints for managing user accounts in your tenant. All endpoints are located at /tenant/{tenantId}/api/Users.

Getting a List of Users

To get a paginated list of all users in your tenant, make a GET request to the Users endpoint. The response includes user information such as email, display name, enabled status, and MFA settings.

Example: Get a list of users

// Using HttpClient with authentication
var tenantId = "your-tenant-id";
var apiKey = "your-api-key"; // Or use JWT token with Admin group

var response = await httpClient.GetAsync(
    $"https://auth.agglestone.com/tenant/{tenantId}/api/Users?pageNumber=1&pageSize=10",
    headers: {
        "Authorization": "Bearer {jwt-token}" // Or "X-API-Key": apiKey
    }
);

var users = await response.Content.ReadFromJsonAsync<PagedResponse<UserResponse>>();

// Using fetch
const tenantId = 'your-tenant-id';
const apiKey = 'your-api-key'; // Or use JWT token with Admin group

const response = await fetch(
  `https://auth.agglestone.com/tenant/${tenantId}/api/Users?pageNumber=1&pageSize=10`,
  {
    headers: {
      'Authorization': `Bearer ${jwtToken}` // Or 'X-API-Key': apiKey
    }
  }
);

const users = await response.json();

# Using httpx
tenant_id = "your-tenant-id"
api_key = "your-api-key"  # Or use JWT token with Admin group

response = await client.get(
    f"https://auth.agglestone.com/tenant/{tenant_id}/api/Users?pageNumber=1&pageSize=10",
    headers={
        "Authorization": f"Bearer {jwt_token}"  # Or "X-API-Key": api_key
    }
)

users = response.json()

The response includes pagination information and an array of user objects with properties like userId, email, displayName, enabled, requirePasswordReset, requireTOTP, and more.

User Endpoints

GET /tenant/{tenantId}/api/Users

Retrieves a paginated list of all users in the tenant. Supports pageNumber and pageSize query parameters (default: page 1, 10 per page, max 100 per page).

Response: Returns a PagedResponse with user data and pagination information.

GET /tenant/{tenantId}/api/Users/{userId}

Retrieves details for a specific user by their user ID.

Response: Returns a UserResponse object with the user’s information.

POST /tenant/{tenantId}/api/Users

Creates a new user account in the tenant. Requires an email address. Optionally accepts displayName, userType, enabled, password, and requirePasswordReset.

Request Body: CreateUserRequest with required email and optional fields.

Response: Returns a UserIdResponse with the newly created user’s ID (201 Created).

PUT /tenant/{tenantId}/api/Users/{userId}

Updates an existing user’s information. You can update email, display name, password, enabled status, password reset requirement, MFA requirement, and MFA reset flag. All fields are optional—only include the fields you want to update.

Request Body: UpdateUserRequest with optional fields to update.

Response: Returns a UserIdResponse with the user’s ID (200 OK).

DELETE /tenant/{tenantId}/api/Users/{userId}

Deletes a user from the tenant. This permanently removes the user account.

Response: Returns 204 No Content on success.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

Groups

The Groups API provides endpoints for managing groups in your tenant. All endpoints are located at /tenant/{tenantId}/api/Groups.

Getting a List of Groups

To get a paginated list of all groups in your tenant, make a GET request to the Groups endpoint. The response includes group information such as group name and description.

Example: Get a list of groups

// Using HttpClient with authentication
var tenantId = "your-tenant-id";
var apiKey = "your-api-key"; // Or use JWT token with Admin group

var response = await httpClient.GetAsync(
    $"https://auth.agglestone.com/tenant/{tenantId}/api/Groups?pageNumber=1&pageSize=10",
    headers: {
        "Authorization": "Bearer {jwt-token}" // Or "X-API-Key": apiKey
    }
);

var groups = await response.Content.ReadFromJsonAsync<PagedResponse<GroupResponse>>();

// Using fetch
const tenantId = 'your-tenant-id';
const apiKey = 'your-api-key'; // Or use JWT token with Admin group

const response = await fetch(
  `https://auth.agglestone.com/tenant/${tenantId}/api/Groups?pageNumber=1&pageSize=10`,
  {
    headers: {
      'Authorization': `Bearer ${jwtToken}` // Or 'X-API-Key': apiKey
    }
  }
);

const groups = await response.json();

# Using httpx
tenant_id = "your-tenant-id"
api_key = "your-api-key"  # Or use JWT token with Admin group

response = await client.get(
    f"https://auth.agglestone.com/tenant/{tenant_id}/api/Groups?pageNumber=1&pageSize=10",
    headers={
        "Authorization": f"Bearer {jwt_token}"  # Or "X-API-Key": api_key
    }
)

groups = response.json()

The response includes pagination information and an array of group objects with properties like id, groupName, and description.

Group Endpoints

GET /tenant/{tenantId}/api/Groups

Retrieves a paginated list of all groups in the tenant. Supports pageNumber and pageSize query parameters (default: page 1, 10 per page, max 100 per page).

Response: Returns a PagedResponse with group data and pagination information.

GET /tenant/{tenantId}/api/Groups/{id}

Retrieves details for a specific group by its group ID.

Response: Returns a GroupResponse object with the group’s information.

POST /tenant/{tenantId}/api/Groups

Creates a new group in the tenant. Requires a group name. Optionally accepts a description.

Request Body: CreateGroupRequest with required groupName and optional description.

Response: Returns a GroupIdResponse with the newly created group’s ID (201 Created).

PUT /tenant/{tenantId}/api/Groups/{id}

Updates an existing group’s name and description. Both fields are optional—only include the fields you want to update.

Request Body: UpdateGroupRequest with optional groupName and description fields.

Response: Returns a GroupIdResponse with the group’s ID (200 OK).

DELETE /tenant/{tenantId}/api/Groups/{id}

Deletes a group from the tenant. This permanently removes the group. Note that deleting a group does not remove users from that group—you’ll need to update users separately to remove group memberships.

Response: Returns 204 No Content on success.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

—

Ready to learn more? Check out the Quick Start Guide to see how to get authentication working, or learn about Validating JWTs in Your Backend for user authentication.