Skip to main content

Managing Users & Groups

This guide shows you how to programmatically manage users and groups in User Tasks Bridge using the REST API. These operations require admin privileges and are typically used for administrative tasks like onboarding new users, creating groups, and managing group memberships.

note

All API endpoints require authentication. You must include a valid access token in the Authorization header as a Bearer token. The examples below show how to make these calls using standard HTTP libraries.

Managing Users​

Creating a User​

To create a new user in your IdP, make a POST request to the create user endpoint:

const response = await fetch('http://localhost:8089/default/management/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    username: 'john.doe',
    email: 'john.doe@example.com',
  }),
});

if (response.status === 201) {
  console.log('User created successfully');
} else {
  const error = await response.json();
  console.error('Error creating user:', error);
}

Request Body:

  • firstName (string, optional): User's first name
  • lastName (string, optional): User's last name
  • username (string, optional): Unique username
  • email (string, optional): User's email address

Note: At least one of the fields (firstName, lastName, username, or email) must be provided.

Response:

  • 201 Created: User successfully created (no response body)
  • 400 Bad Request: Cannot create user while missing all properties
  • 401 Unauthorized: Invalid or missing authentication token
  • 406 Not Acceptable: Unknown Identity vendor
  • 409 Conflict: User already exists with requested username and/or email

Listing Users​

To retrieve a list of users from your IdP:

const response = await fetch(
  'http://localhost:8089/default/management/users?max_results=50',
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

if (response.ok) {
  const data = await response.json();
  console.log('Users:', data.users);
} else {
  const error = await response.json();
  console.error('Error listing users:', error);
}

Query Parameters:

  • email (string, optional): Filter by email address
  • first_name (string, optional): Filter by first name
  • last_name (string, optional): Filter by last name
  • username (string, optional): Filter by username
  • user_group_id (string, optional): Filter by group membership
  • first_result (integer, optional): Pagination offset (default: 0)
  • max_results (integer, optional): Maximum number of results (default: 10)

Response:

  • 200 OK: Returns a list of users with their profile information, groups, and roles
  • 401 Unauthorized: Invalid or missing authentication token
  • 406 Not Acceptable: Unknown Identity vendor

Getting a Single User​

To retrieve details about a specific user:

const userId = 'user@example.com'; // or UUID, depending on your user-id-claim config
const response = await fetch(
  `http://localhost:8089/default/management/users/${userId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

if (response.ok) {
  const user = await response.json();
  console.log('User details:', user);
} else {
  const error = await response.json();
  console.error('Error getting user:', error);
}

Response:

  • 200 OK: User found, returns user details
  • 401 Unauthorized: Invalid or missing authentication token
  • 404 Not Found: User data could not be found
  • 406 Not Acceptable: Unknown Identity vendor

Updating a User​

To update a user's properties:

const userId = 'user@example.com';
const response = await fetch(
  `http://localhost:8089/default/management/users/${userId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      firstName: 'Jane',
      lastName: 'Smith',
      username: 'jane.smith',
      email: 'jane.smith@example.com',
      enabled: true,
    }),
  }
);

if (response.status === 204) {
  console.log('User updated successfully');
} else {
  const error = await response.json();
  console.error('Error updating user:', error);
}

Request Body:

  • firstName (string, optional): Updated first name
  • lastName (string, optional): Updated last name
  • username (string, optional): Updated username
  • email (string, optional): Updated email address
  • enabled (boolean, optional): Whether the user account is enabled

Response:

  • 204 No Content: User successfully updated
  • 400 Bad Request: Validation error (e.g., cannot set email to null if user-id-claim is EMAIL)
  • 401 Unauthorized: Invalid or missing authentication token
  • 406 Not Acceptable: Unknown Identity vendor

Deleting a User​

To delete a user from your IdP:

const userId = 'user@example.com';
const response = await fetch(
  `http://localhost:8089/default/management/users/${userId}?ignore_orphan_tasks=false`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

if (response.status === 204) {
  console.log('User deleted successfully');
} else {
  const error = await response.json();
  console.error('Error deleting user:', error);
}

Query Parameters:

  • ignore_orphan_tasks (boolean, optional): If true, allows deletion even if the user has assigned tasks. Default: false

Response:

  • 204 No Content: User successfully deleted
  • 400 Bad Request: No matching user found
  • 401 Unauthorized: Invalid or missing authentication token
  • 406 Not Acceptable: Unknown Identity vendor
  • 409 Conflict: User cannot be deleted because there are UserTaskRuns already assigned and waiting to be completed, or admin user is forbidden from deleting themselves

Managing Groups​

Creating a Group​

To create a new group:

const response = await fetch('http://localhost:8089/default/management/groups', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'approvers',
  }),
});

if (response.status === 201) {
  console.log('Group created successfully');
} else {
  const error = await response.json();
  console.error('Error creating group:', error);
}

Request Body:

  • name (string, required): Unique group name

Response:

  • 201 Created: Group successfully created (no response body)
  • 400 Bad Request: Validation error (name must not be blank)
  • 401 Unauthorized: Invalid or missing authentication token
  • 406 Not Acceptable: Unknown Identity vendor
  • 409 Conflict: Group name already exists

Listing Groups​

To retrieve all groups (admin endpoint):

const response = await fetch(
  'http://localhost:8089/default/management/groups?max_results=50',
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

if (response.ok) {
  const data = await response.json();
  console.log('Groups:', data.groups);
} else {
  const error = await response.json();
  console.error('Error listing groups:', error);
}

Query Parameters:

  • name (string, optional): Filter by group name
  • first_result (integer, optional): Pagination offset (default: 0)
  • max_results (integer, optional): Maximum number of results (default: 10)

Response:

  • 200 OK: Returns a list of groups with their IDs, names, and validity status
  • 401 Unauthorized: Invalid or missing authentication token
  • 406 Not Acceptable: Unknown Identity vendor

Adding a User to a Group​

To add a user to a group (also called "joining a group"):

const userId = 'user@example.com';
const groupId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'; // Use the group ID (UUID)
const response = await fetch(
  `http://localhost:8089/default/management/users/${userId}/groups/${groupId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

if (response.status === 204) {
  console.log('User added to group successfully');
} else {
  const error = await response.json();
  console.error('Error adding user to group:', error);
}

Important: Use the group ID (UUID), not the group name, in the URL path. You can get the group ID by listing groups first.

Response:

  • 204 No Content: User successfully added to group
  • 401 Unauthorized: Invalid or missing authentication token
  • 404 Not Found: User or group not found
  • 406 Not Acceptable: Unknown Identity vendor

Removing a User from a Group​

To remove a user from a group:

const userId = 'user@example.com';
const groupId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'; // Use the group ID (UUID)
const response = await fetch(
  `http://localhost:8089/default/management/users/${userId}/groups/${groupId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

if (response.status === 204) {
  console.log('User removed from group successfully');
} else {
  const error = await response.json();
  console.error('Error removing user from group:', error);
}

Important: Use the group ID (UUID), not the group name, in the URL path.

Response:

  • 204 No Content: User successfully removed from group
  • 401 Unauthorized: Invalid or missing authentication token
  • 404 Not Found: User or group not found
  • 406 Not Acceptable: Unknown Identity vendor

Complete Example: User Onboarding​

Here's a complete example that creates a user, creates a group, and adds the user to the group:

async function onboardUser(userData, groupName) {
  const baseUrl = 'http://localhost:8089/default';
  const headers = {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  };

  try {
    // Step 1: Create the user
    const createUserResponse = await fetch(`${baseUrl}/management/users`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        firstName: userData.firstName,
        lastName: userData.lastName,
        username: userData.username,
        email: userData.email,
      }),
    });

    if (createUserResponse.status !== 201) {
      throw new Error(`Failed to create user: ${await createUserResponse.text()}`);
    }

    console.log('User created successfully');

    // Step 2: Create the group (if it doesn't exist)
    // Note: This will fail with 409 if the group already exists, which is fine
    const createGroupResponse = await fetch(`${baseUrl}/management/groups`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ name: groupName }),
    });

    if (createGroupResponse.status === 409) {
      console.log(`Group "${groupName}" already exists`);
    } else if (createGroupResponse.status !== 201) {
      throw new Error(`Failed to create group: ${await createGroupResponse.text()}`);
    } else {
      console.log('Group created successfully');
    }

    // Step 3: Get the group ID by listing groups
    const listGroupsResponse = await fetch(
      `${baseUrl}/management/groups?name=${groupName}`,
      {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
        },
      }
    );

    if (!listGroupsResponse.ok) {
      throw new Error(`Failed to list groups: ${await listGroupsResponse.text()}`);
    }

    const groupsData = await listGroupsResponse.json();
    const group = groupsData.groups.find((g) => g.name === groupName);

    if (!group) {
      throw new Error(`Group "${groupName}" not found`);
    }

    // Step 4: Add user to group using the group ID
    // Use the user ID format based on your user-id-claim configuration
    const userId = userData.email; // or user.id if using SUB
    const joinGroupResponse = await fetch(
      `${baseUrl}/management/users/${userId}/groups/${group.id}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
        },
      }
    );

    if (joinGroupResponse.status !== 204) {
      throw new Error(`Failed to add user to group: ${await joinGroupResponse.text()}`);
    }

    console.log(`User ${userId} successfully added to group ${groupName}`);
    return { user: userData, groupName };
  } catch (error) {
    console.error('Error during user onboarding:', error);
    throw error;
  }
}

// Usage
await onboardUser(
  {
    firstName: 'Alice',
    lastName: 'Johnson',
    username: 'alice.johnson',
    email: 'alice.johnson@example.com',
  },
  'developers'
);

Understanding User ID Formats​

When working with user management endpoints, the user ID format depends on your backend's user-id-claim configuration:

  • SUB: Use the user's UUID (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
  • EMAIL: Use the user's email address (e.g., "user@example.com")
  • PREFERRED_USERNAME: Use the user's preferred username (e.g., "john.doe")

Check your backend configuration to determine which format to use. The user-id-claim is configured in your oidc-properties.yml file. For details on how to configure this, see The Basics (OIDC).

API Reference​

This guide covers the most commonly used endpoints for managing users and groups. For complete API documentation, including additional endpoints like setting user passwords, updating/deleting groups, and assigning admin roles, see: