User and Group Management

Last updated: December 2025

Ready to manage your users and groups like a pro? 🎯 This guide shows you how to create, update, and delete users, organize them into groups, and manage their permissions. It’s like having your own user management superpowers!

Overview

Our system supports:

User Management: Create, read, update, and delete users
Group Management: Organize users into groups for access control
Role-Based Access: Control access based on group membership
User Attributes: Email, display name, user type, enabled status, and more

Authentication Requirements

All user and group management endpoints require:

JWT Bearer Token (from OAuth2/OIDC login) with Admin group membership, OR
API Key authentication (for server-to-server operations)

See API Keys vs JWT Tokens for more details.

User Management

Base URL Pattern

All user endpoints follow this pattern:

/tenant/{tenantId}/api/Users

Get All Users

Retrieve a paginated list of all users in your tenant.

Endpoint: GET /tenant/{tenantId}/api/Users

Query Parameters:

pageNumber (optional, default: 1) – Page number
pageSize (optional, default: 10, max: 100) – Number of users per page

Request Example:

const response = await fetch(
  'https://auth.agglestone.com/tenant/{tenantId}/api/Users?pageNumber=1&pageSize=20',
  {
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    }
  }
);

Response:

{
  "data": [
    {
      "userId": "f3e89bb2-5827-4e4b-8b33-823b48327ec7",
      "email": "user@example.com",
      "displayName": "John Doe",
      "userType": "Standard",
      "enabled": true,
      "lastLoggedIn": "2024-01-15T10:30:00Z",
      "lastTokenRefresh": "2024-01-15T12:00:00Z",
      "owner": false,
      "requirePasswordReset": false
    }
  ],
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 45
}

Get User by ID

Retrieve details for a specific user.

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

Request Example:

const userId = 'f3e89bb2-5827-4e4b-8b33-823b48327ec7';
const response = await fetch(
  `https://auth.agglestone.com/tenant/{tenantId}/api/Users/${userId}`,
  {
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    }
  }
);

Response:

{
  "userId": "f3e89bb2-5827-4e4b-8b33-823b48327ec7",
  "email": "user@example.com",
  "displayName": "John Doe",
  "userType": "Standard",
  "enabled": true,
  "lastLoggedIn": "2024-01-15T10:30:00Z",
  "lastTokenRefresh": "2024-01-15T12:00:00Z",
  "owner": false,
  "requirePasswordReset": false
}

Create User

Create a new user account in your tenant.

Endpoint: POST /tenant/{tenantId}/api/Users

Request Body:

{
  "email": "newuser@example.com",
  "displayName": "Jane Smith",
  "userType": "Standard",
  "enabled": true,
  "password": "SecurePassword123!",
  "requirePasswordReset": true
}

Request Example:

const response = await fetch(
  'https://auth.agglestone.com/tenant/{tenantId}/api/Users',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'newuser@example.com',
      displayName: 'Jane Smith',
      userType: 'Standard',
      enabled: true,
      password: 'SecurePassword123!',
      requirePasswordReset: true
    })
  }
);

Response (201 Created):

{
  "userId": "a1b2c3d4-5678-90ab-cdef-123456789abc"
}

Notes:

Email must be unique within the tenant
If password is not provided, user will need to set it via password reset
New users are automatically added to the Tenant Administrator group
requirePasswordReset defaults to true if not specified

Update User

Update an existing user’s information.

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

Request Body (all fields optional):

{
  "email": "updated@example.com",
  "displayName": "Updated Name",
  "userType": "Premium",
  "enabled": false,
  "password": "NewPassword123!",
  "requirePasswordReset": true
}

Request Example:

const userId = 'f3e89bb2-5827-4e4b-8b33-823b48327ec7';
const response = await fetch(
  `https://auth.agglestone.com/tenant/{tenantId}/api/Users/${userId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      displayName: 'Updated Name',
      enabled: true
    })
  }
);

Response (200 OK):

{
  "userId": "f3e89bb2-5827-4e4b-8b33-823b48327ec7"
}

Notes:

Only include fields you want to update
Email changes must be unique within the tenant
Password changes automatically set requirePasswordReset to true unless explicitly set to false

Delete User

Delete a user from your tenant.

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

Request Example:

const userId = 'f3e89bb2-5827-4e4b-8b33-823b48327ec7';
const response = await fetch(
  `https://auth.agglestone.com/tenant/{tenantId}/api/Users/${userId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer {access_token}'
    }
  }
);

Response (204 No Content)

Restrictions:

You cannot delete your own account
You cannot delete the last admin user in the tenant

Group Management

Groups allow you to organize users and control access. Users can belong to multiple groups.

Base URL Pattern

All group endpoints follow this pattern:

/tenant/{tenantId}/api/Groups

Get All Groups

Retrieve a paginated list of all groups in your tenant.

Endpoint: GET /tenant/{tenantId}/api/Groups

Query Parameters:

pageNumber (optional, default: 1) – Page number
pageSize (optional, default: 10, max: 100) – Number of groups per page

Request Example:

const response = await fetch(
  'https://auth.agglestone.com/tenant/{tenantId}/api/Groups?pageNumber=1&pageSize=20',
  {
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    }
  }
);

Response:

{
  "data": [
    {
      "id": "501b38ea-16af-4cd2-9f20-35675d2c001e",
      "groupName": "Tenant Administrators",
      "description": "Users with administrative privileges"
    },
    {
      "id": "a1b2c3d4-5678-90ab-cdef-123456789abc",
      "groupName": "Developers",
      "description": "Development team members"
    }
  ],
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 5
}

Get Group by ID

Retrieve details for a specific group.

Endpoint: GET /tenant/{tenantId}/api/Groups/{groupId}

Request Example:

const groupId = 'a1b2c3d4-5678-90ab-cdef-123456789abc';
const response = await fetch(
  `https://auth.agglestone.com/tenant/{tenantId}/api/Groups/${groupId}`,
  {
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    }
  }
);

Response:

{
  "id": "a1b2c3d4-5678-90ab-cdef-123456789abc",
  "groupName": "Developers",
  "description": "Development team members"
}

Create Group

Create a new group in your tenant.

Endpoint: POST /tenant/{tenantId}/api/Groups

Request Body:

{
  "groupName": "Marketing Team",
  "description": "Marketing department members"
}

Request Example:

const response = await fetch(
  'https://auth.agglestone.com/tenant/{tenantId}/api/Groups',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      groupName: 'Marketing Team',
      description: 'Marketing department members'
    })
  }
);

Response (201 Created):

{
  "id": "b2c3d4e5-6789-01ab-cdef-23456789abcd"
}

Update Group

Update an existing group’s name and description.

Endpoint: PUT /tenant/{tenantId}/api/Groups/{groupId}

Request Body (all fields optional):

{
  "groupName": "Updated Group Name",
  "description": "Updated description"
}

Request Example:

const groupId = 'a1b2c3d4-5678-90ab-cdef-123456789abc';
const response = await fetch(
  `https://auth.agglestone.com/tenant/{tenantId}/api/Groups/${groupId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      groupName: 'Updated Group Name',
      description: 'Updated description'
    })
  }
);

Response (200 OK):

{
  "id": "a1b2c3d4-5678-90ab-cdef-123456789abc"
}

Delete Group

Delete a group from your tenant.

Endpoint: DELETE /tenant/{tenantId}/api/Groups/{groupId}

Request Example:

const groupId = 'a1b2c3d4-5678-90ab-cdef-123456789abc';
const response = await fetch(
  `https://auth.agglestone.com/tenant/{tenantId}/api/Groups/${groupId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer {access_token}'
    }
  }
);

Response (204 No Content)

Note: Deleting a group does not delete users, but removes their membership in that group.

Managing User-Group Relationships

User-group relationships are managed through the user object. When you update a user, you can modify their groups array. However, the current API doesn’t expose direct endpoints for adding/removing users from groups. You would need to:

Get the user’s current groups
Modify the groups array
Update the user with the new groups array

Note: This functionality may be enhanced in future API versions.

Default Groups

Tenant Administrators

Every tenant has a default “Tenant Administrators” group with ID: 501b38ea-16af-4cd2-9f20-35675d2c001e

Users in this group have:

Full access to user and group management
Ability to manage API keys
Administrative privileges

New users are automatically added to this group when created.

Error Handling

Common Errors

401 Unauthorized

Missing or invalid authentication token
User doesn’t have Admin group membership
Solution: Check your authentication token and user permissions

404 Not Found

User or group doesn’t exist
User/group belongs to a different tenant
Solution: Verify the ID and tenant ID

400 Bad Request

Invalid request body
Missing required fields
Solution: Check request format and required fields

409 Conflict

Email already exists in tenant
Solution: Use a different email or update existing user

Complete Examples

Create User and Assign to Group

// 1. Create a new user
const createUserResponse = await fetch(
  'https://auth.agglestone.com/tenant/{tenantId}/api/Users',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {access_token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'developer@example.com',
      displayName: 'Developer User',
      userType: 'Standard',
      enabled: true,
      password: 'TempPassword123!',
      requirePasswordReset: true
    })
  }
);

const { userId } = await createUserResponse.json();

// 2. Get the Developers group ID (assuming you know it or fetched it earlier)
const developersGroupId = 'a1b2c3d4-5678-90ab-cdef-123456789abc';

// 3. Update user to add them to the Developers group
// Note: This requires getting current groups first, then updating
// This is a simplified example - you'd need to fetch current groups first

List All Users with Pagination

async function getAllUsers(pageNumber = 1, pageSize = 20) {
  const response = await fetch(
    `https://api.agglestone.com/tenant/{tenantId}/api/Users?pageNumber=${pageNumber}&pageSize=${pageSize}`,
    {
      headers: {
        'Authorization': 'Bearer {access_token}',
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error('Failed to fetch users');
  }
  
  const data = await response.json();
  return data;
}

// Usage
const users = await getAllUsers(1, 20);
console.log(`Total users: ${users.totalRecords}`);
console.log(`Page ${users.pageNumber} of ${Math.ceil(users.totalRecords / users.pageSize)}`);
users.data.forEach(user => {
  console.log(`${user.displayName} (${user.email})`);
});

Best Practices

Pagination: Always use pagination when fetching lists to avoid performance issues
Error Handling: Implement proper error handling for all API calls
Token Refresh: Ensure access tokens are refreshed before expiry
Validation: Validate user input before creating/updating users
Security: Never log or expose passwords or tokens
Group Management: Use groups to organize users and manage permissions efficiently

Next Steps

Learn about API Keys vs JWT Tokens for server-to-server operations
Check out Code Examples for complete implementations