Skip to main content

User Group Endpoints

This document provides detailed information about the user-group endpoints in the Amove API. A user group is an account-scoped collection of users that can be granted permissions on projects and shared cloud drives collectively.

Endpoints​

  1. Get All User Groups
  2. Get All User Groups With Details
  3. Insert User Group
  4. Update User Group
  5. Delete User Group
  6. Get Assigned Users
  7. Get Assigned User Groups
  8. Assign Users
  9. Unassign User
  10. Import Users

Get All User Groups​

Returns a paginated list of user groups in the current user's account.

  • URL: /api/v1/usergroup/get_all
  • Method: GET
  • Auth Required: Yes

Query Parameters​

ParameterTypeDefaultDescription
pageinteger1Starting page
pagesizeinteger50Page size
sortfieldstring"Name"Field to sort by
descendingbooleanfalseSort direction
deletedbooleanfalseWhen true, return soft-deleted groups instead of active ones
namestringnullOptional case-insensitive substring filter on group name

Response​

Returns a DTOCollection<UserGroup>:

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "name": "Engineering",
      "description": "Engineering department",
      "active": true,
      "deleted": false
    }
  ],
  "total": 1
}

Get All User Groups With Details​

Same filters and paging as Get All User Groups, but each group is returned with its assigned projects, member users, and shared cloud drives inline.

  • URL: /api/v1/usergroup/get_all_with_details
  • Method: GET
  • Auth Required: Yes

Query Parameters​

ParameterTypeDefaultDescription
pageinteger1Starting page
pagesizeinteger50Page size
sortfieldstring"Name"Field to sort by
descendingbooleanfalseSort direction
deletedbooleanfalseWhen true, return soft-deleted groups
namestringnullOptional case-insensitive substring filter on group name

Response​

Returns a DTOCollection<UserGroupWithDetailsDTO>. Each item:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Engineering",
  "description": "Engineering department",
  "projectsData": [
    { "project": { }, "permission": { } }
  ],
  "usersData": [
    { "user": { }, "userUserGroup": { } }
  ],
  "drivesData": [
    { "sharedCloudDrive": { }, "permission": { } }
  ]
}

Insert User Group​

Creates a new user group under the current user's account. The server overrides accountId with the caller's account id.

  • URL: /api/v1/usergroup/insert
  • Method: POST
  • Auth Required: Yes

Request Body​

{
  "name": "string (max 100)",
  "description": "string",
  "active": true
}

Response​

Returns the newly-created UserGroup object.

Update User Group​

Updates an existing user group. accountId is always reset to the caller's account.

  • URL: /api/v1/usergroup/update
  • Method: PUT
  • Auth Required: Yes

Request Body​

A full UserGroup object including the id of the record to update.

Response​

Returns the updated UserGroup.

Delete User Group​

Soft-deletes a user group. Because UserGroup implements ILogicalDeleteableEntity, the record is marked Deleted = true rather than physically removed.

  • URL: /api/v1/usergroup/delete
  • Method: DELETE
  • Auth Required: Yes

Query Parameters​

ParameterTypeDescription
idstring (uuid)Id of the user group to delete

Response​

A 200 OK status with no body on success.

Get Assigned Users​

Lists the users in a given user group. Soft-deleted users are excluded.

  • URL: /api/v1/usergroup/get_assigned_users
  • Method: GET
  • Auth Required: Yes

Query Parameters​

ParameterTypeDefaultDescription
userGroupIdstring (uuid)—User group whose members to list
pageinteger1Starting page
pagesizeinteger50Page size
sortfieldstring"User.Username"Field to sort by
descendingbooleanfalseSort direction
usernamestringnullOptional case-insensitive substring filter on username

Response​

Returns a DTOCollection<UserUserGroupDTO>. Each item contains the full User and the joining UserUserGroup record.

Get Assigned User Groups​

Lists the user groups a given user belongs to. Soft-deleted groups are excluded.

  • URL: /api/v1/usergroup/get_assigned_usergroups
  • Method: GET
  • Auth Required: Yes

Query Parameters​

ParameterTypeDefaultDescription
userIdstring (uuid)—User whose group memberships to list
pageinteger1Starting page
pagesizeinteger50Page size
sortfieldstring"UserGroup.Name"Field to sort by
descendingbooleanfalseSort direction
namestringnullOptional case-insensitive substring filter on group name

Response​

Returns a DTOCollection<UserUserGroupDTO>. Each item contains the full UserGroup and the joining UserUserGroup record.

Assign Users​

Adds one or more users to user groups. Existing (UserId, UserGroupId) pairs are skipped silently.

  • URL: /api/v1/usergroup/assign_users
  • Method: POST
  • Auth Required: Yes

Request Body​

An array of UserUserGroup entries:

[
  {
    "userId": "00000000-0000-0000-0000-000000000000",
    "userGroupId": "00000000-0000-0000-0000-000000000000"
  }
]

Response​

A 200 OK status with no body on success.

Unassign User​

Removes a single user-to-group membership.

  • URL: /api/v1/usergroup/unassign_user
  • Method: DELETE
  • Auth Required: Yes

Query Parameters​

ParameterTypeDescription
idstring (uuid)Id of the UserUserGroup record to delete

Response​

A 200 OK status with no body on success.

Import Users​

Bulk-imports users into user groups. For each entry: if the user already exists in the caller's account it is reused; if the username exists in a different account the entry is skipped; otherwise a new user is created and the caller's billing subscription is extended to include the new seat (subscription status must be Active). Each named user group is created if absent, and the user is assigned to it. Group and user creation are additive; existing assignments are left intact.

  • URL: /api/v1/usergroup/import_users
  • Method: POST
  • Auth Required: Yes

If the current user has no active billing subscription, the endpoint returns HTTP 402 Payment Required before doing any work.

Request Body​

An array of UserUserGroupRelation:

[
  {
    "user": {
      "username": "user@example.com",
      "email": "user@example.com",
      "userType": 64
    },
    "userGroups": [
      { "name": "Engineering" }
    ]
  }
]
  • user.userType — UserType flag: 16 DesktopAdmin, 32 DesktopCreativeUser, 64 DesktopStandardUser.
  • userGroups — list of groups to join (matched case-insensitively by name; created when missing).

Response​

A 200 OK status with no body on success.

Sample Code​

Create a group and import users into it​

Python
import requests

JWT = "YOUR_JWT"
BASE = "https://api.amove.io"

group = requests.post(
    f"{BASE}/api/v1/usergroup/insert",
    headers={"Authorization": f"Bearer {JWT}"},
    json={"name": "Engineering", "description": "Engineering department", "active": True},
).json()

requests.post(
    f"{BASE}/api/v1/usergroup/import_users",
    headers={"Authorization": f"Bearer {JWT}"},
    json=[{
        "user": {
            "username": "user@example.com",
            "email": "user@example.com",
            "userType": 64
        },
        "userGroups": [{"name": "Engineering"}]
    }],
)
JavaScript
const JWT = "YOUR_JWT";
const BASE = "https://api.amove.io";

const group = await fetch(`${BASE}/api/v1/usergroup/insert`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${JWT}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Engineering", description: "Engineering department", active: true })
}).then(r => r.json());

await fetch(`${BASE}/api/v1/usergroup/import_users`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${JWT}`, "Content-Type": "application/json" },
  body: JSON.stringify([{
    user: { username: "user@example.com", email: "user@example.com", userType: 64 },
    userGroups: [{ name: "Engineering" }]
  }])
});

Assign existing users to an existing group​

C#
using System.Net.Http;
using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_JWT");

var payload = new[]
{
    new
    {
        userId = Guid.Parse("00000000-0000-0000-0000-000000000000"),
        userGroupId = Guid.Parse("00000000-0000-0000-0000-000000000000")
    }
};

await client.PostAsJsonAsync("https://api.amove.io/api/v1/usergroup/assign_users", payload);

For error handling, see Error Model.