---
updatedAt: 2026-04-30T11:45:19.000Z
agentTools:
  projectIndex: https://developer.ixon.cloud/llms.txt
---

# Manage groups, users, roles and more

In this article you will find complete information about the management of groups and their hierarchy, users, invites, roles and access categories.

# Introduction to User Management and related endpoints

The **management of users** can be integrated in custom applications by using the API. You will be able to do perform actions such as integrating an IXON Cloud **user invite** in your own online environment, or **fetching/adding** a list of users, **removing** a user, but also **fetching/manipulating roles, groups, access categories and types**. After you have obtained the **basic information headers** (**<Anchor label="ApplicationId" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-prerequisites#how-to-request-an-application-id">ApplicationId</Anchor>**, <Anchor label="**Bearer Token**" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-authentication-headers#how-to-get-a-bearer-token">**Bearer Token**</Anchor> and <Anchor label="**CompanyId**" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-prerequisites#how-to-get-a-companys-publicid">**CompanyId**</Anchor>) you will be able to use the following endpoints to perform such actions.

The purpose of this article is to illustrate a **technical overview** of the mechanisms of IXON's user management system and its relative API endpoints. For more information and for a fresh set up and more information about roles, groups, permissions and more, it is highly recommended to check out this <Anchor label="support article" target="_blank" href="https://support.ixon.cloud/s/article/User-management-setup-guide">support article</Anchor> as well as the whole **User management** section for a deep dive into this topic from a user-friendly perspective.

> 👍 Field selection
>
> Using `?fields=*` will not always work to select every field belonging to a JSON response, as some elements are mapped as objects (e.g. `parent` in **GroupList**). For this reason, in many cURL commands you will notice fields written in a different syntax.
>
> Let's take *GroupList (GET)* as an example: in this case, you will write `agent.publicId` to select just the agent's public ID, or `parent.*` to select all the fields of the parent object.

***

# Before you start: how to visualize groups

> 📘 Required module
>
> To visualize the **Hierarchical user groups** in your company, you will need the **Subgroups** module. Check your modules at <Anchor label="**Admin > Licenses**" target="_blank" href="https://portal.ixon.cloud/admin/licenses">**Admin > Licenses**</Anchor>. To obtain this module, contact your IXON account manager or IXON distributor.

## Hierarchical tree

Provided that you have already obtained the required module as mentioned in the note above, you will then be able to create both *groups* and *subgroups* represented as a hierarchical tree. This can be useful in case you need to divide different sectors or teams into subgroups and to better structure roles and permissions.

We will use the **Packaging Factories** and **Propack Engineering** groups as examples throughout this article:

![](https://files.readme.io/f71e7523ecbcb7e946b8560bedeaf24404ef30dac03c75740b713eaef04dc394-Full_Image.png)

In this type of visualization there are a few differences that we can point out:

* Each **group** will display how many **devices** are assigned to it and how many **users** are related to it. The latter is set up by assigning **roles** to users.
* Each **group type** will have its own **color**, which is **required** and which you can customize. You can do so in this interface by clicking on the "+" near *Group Types*:

  <Image align="center" border={true} src="https://files.readme.io/b3cc1c304f71bcb1a9b1e83112bf71c5093e241b3fcacf74564ea9b75838a982-image.png" className="border" />
* Unlike in the standard group interface, which represents the groups as a list with no subgroups available, you will now see the groups represented in the form of a **hierarchical tree**, which can be either made **vertical** or **horizontal** by clicking on the icons on the top right:

  <Image align="center" border={true} src="https://files.readme.io/875369bc6c0a9e903b2987469035aa4ef9bdb9095342eee38802b10483d7ee60-image.png" className="border" />
* The hierarchy of the *group types*, *groups* and *subgroups* is also visible in the form of a **hierarchical list** positioned to the left of the tree, and which can be interacted with to **create new subgroups** and to **rename or delete existing ones** with the "Edit" or "Remove" buttons respectively:

  <Image align="center" border={true} src="https://files.readme.io/aac42002b356fcf831b572ed63893e446e2a9863f4c2cf9f8d557dab31775fc3-image.png" className="border" />

> 👍 Subgroups of a subgroup
>
> Needless to say, each *Customer* can have **their own subgroups**, which can also be of a different type.

## Standard group view

Without the **Subgroups** module, you will see the default view of your groups:

<Image align="center" border={true} src="https://files.readme.io/2f18b2ab9d7ecc240b876871264e91d8ef18dca5b3545fea3cfa75de105da59c-image.png" className="border" />

What we can see here is that we still have the possibility to set up group types on the bottom left and then assign groups to them, such as *Customer 1*, *Customer 2*, etc. to **Customer**. We can notice a few differences:

* The groups do not need a **hierarchical tree** representation because the possibility of setting up subgroups is not available.
* There is no color customization available for the group types.
* To see the groups belonging to a different type, such as *Partner*, you will have to switch tab:

  <Image align="center" border={true} src="https://files.readme.io/1f45a6f6371b2f9275cf88d5443a55013d8f41d60cdf9040b5d5acfedb2507e4-image.png" className="border" />

  Consequently, the *P. E. Testing* subgroup would not be a subgroup in this case, but just a simple group, even if it is part of *Propack Engineering*.

***

# User access structure explained

You have probably already noticed the UML diagram shown in the next section. Before taking a closer look to it, it is important to truly comprehend what the elements that populate it are.

## Terminology

This is essentially what the **User access management** consists of:

* **Agent**: a *device* that you can see in the Fleet Manager.
* **AgentMembership**: from an abstract point of view, an agent membership consists of a single **"subscription"** performed by a group to an agent. This occurs when a group is **assigned to an agent**. Let's visualize it:

<Image align="center" alt="This section is found in **Fleet Manager > Devices** when a device of choice is selected. The action of &#x22;adding a group&#x22; **creates the membership**, making it so that a device is &#x22;subscribed&#x22; to an agent. In this case, this agent has two subscribers and therefore two memberships: Customer 1 and Customer 2." border={true} caption="This section is found in **Fleet Manager > Devices** when a device of choice is selected. The action of &#x22;adding a group&#x22; **creates the membership**, making it so that a device is &#x22;subscribed&#x22; to an agent. In this case, this agent has two subscribers and therefore two memberships: Customer 1 and Customer 2. These groups will have access to this agent." src="https://files.readme.io/a73e9f6ff3a69807dc8e897a3088db1a8f764246aef0c9df3a9708b60a3d911b-Add_group.png" />

* **Group**: just like in the general sense, groups are a way to classify units with shared characteristics. For example, *Customer 1* could contain two different groups, one for the customer's sales department and one for the IT department, each with their respective users. They can be found in <Anchor label="**Admin > User management > Groups**" target="_blank" href="https://portal.ixon.cloud/admin/groups">**Admin > User management > Groups**</Anchor>.
* **GroupType**: it is used to define under which "label" a group is. *Customer 1* and *Customer 2* belong to the **Customer** group type. To check your group types, check the *Group types* section on the bottom left in the *Groups* section.
* **User**: anyone who has access to a company. The full list of users can be seen in <Anchor label="**Admin > User management > Users**" target="_blank" href="https://portal.ixon.cloud/admin/users">**Admin > User management > Users**</Anchor>.
* **UserMembership**: similarly to an agent membership, it consists of the **action of assigning a company-wide, group-specific or device-specific role to a user** as seen in the picture below:

  <Image align="center" alt="In **Admin > User management > Users**, when selecting &#x22;Edit user&#x22; (or &#x22;Invite User&#x22;) and then on the &#x22;+&#x22; button, we will see that we can assign three types of roles to a user. In all three cases you will have to select a role, but in the case of group-specific and device-specific roles you will also have to add a **group** and a **device** respectively." border={true} caption="In **Admin > User management > Users**, when selecting &#x22;Edit user&#x22; (or &#x22;Invite User&#x22;) and then on the &#x22;+&#x22; button, we will see that we can assign three types of roles to a user. In all three cases you will have to select a role, but in the case of group-specific and device-specific roles you will also have to add a **group** and a **device** respectively." src="https://files.readme.io/f928d2ff71a8771c42977c44c6b37afcf2c400ccc959dafde4390374dd756572-Edit_User_1.png" />

  <br />
* **Role**: a role determines which permissions a user possesses. You could, for example, create a "Packaging Machines Tester" role where the user can only manage those specific devices. By pressing the *Add role* button in the *Roles* section in **Admin > User management**, you will see an interface with multiple permissions that you can assign to a role.
* **Permissions**: a permission determines what a user can or cannot do. An admin with a company-wide role will be able to manage more than just users or devices. A detailed explanation of what every permission does can be found in this <Anchor label="support article" target="_blank" href="https://support.ixon.cloud/s/article/What-does-each-individual-user-permission-mean">support article</Anchor>.
* **Audience (Access Category)**: an access category defines what a user can or cannot do on a specific device that they have access to. As shown below, there are three types of access categories:

  <Image align="center" alt="The type of access category is optional, but by selecting either Alarm, Page or Service you can decide what to grant access to. A detailed explanation can be found in this [support article](https://support.ixon.cloud/s/article/How-to-use-access-categories)." caption="The type of access category is optional, but by selecting either Alarm, Page or Service you can decide what to grant access to. A detailed explanation can be found in this <Anchor label=&#x22;support article&#x22; target=&#x22;_blank&#x22; href=&#x22;https://support.ixon.cloud/s/article/How-to-use-access-categories&#x22;>support article</Anchor>." src="https://files.readme.io/83d368b17466b0727c1a86711d94402d106c4238b22700db170ca626e975ef96-image.png" />

## Diagram explanation

This **UML diagram** below shows the relationships between *Role, Membership, Audience, Group, etc.*

<Image align="center" border={true} width="90% " src="https://files.readme.io/4963d29-UML-diagram.png" className="border" />

We can describe the relationships in this diagram as follows, starting from the top left:

* A single **Agent** can have multiple **AgentMemberships**.
* Multiple **AgentMemberships** can belong to a single **Group**, which can be assigned to multiple, different agents.
* Multiple **Groups** can have a single **GroupType** assigned to each of them.
* A single **User** can have multiple **UserMemberships**, meaning that a user can have multiple roles assigned to them.
* Multiple **UserMemberships** can belong to a single **Group** or **Role**, meaning that a single group or role can be assigned to multiple users.
* Multiple **Roles** can have one single **Permission**, meaning that a permission (e.g. Manage devices) can be assigned to multiple roles.
* Multiple **Roles** can have one single **Access category**, which can be reassigned to multiple, different roles.

All of these elements and their relationships can be manipulate through the API Endpoints, which will be listed in further subsections of this article. You will read about the most commonly used API endpoints, their verbs and their required fields.

Assuming that you already have an `applicationId`, `companyId` and `bearerToken`, you will now be able to call the following endpoints!

***

# Group management

These are the endpoints concerning manipulation or retrieval of data belonging to **groups**.

> 🚧 Important notes
>
> Please note that:
>
> * The examples provided below are all based off of a company where the **Subgroups** module is available. In case you do not possess that module, the `color` field in the `type` object will have `null` as value.
> * While using the API, you might happen to see a field called `managedBy`. This is a **legacy field**, and therefore it should not be used. You can use `parent` instead.
> * If a group has a **company-wide membership**, the boolean value `isCompanyGroup` in any `Group` object type in a JSON response will be set to `true`. This will be visibile in any other JSON response containing a `Group` object, such as that of the *Group* and *GroupList* endpoints.
> * As seen in the **Admin > Users** section, if you want to assign a *Company-wide* role there will not be any "group" visible, but only "roles". For this reason, **GroupRoleList** only fetches roles making the \`groups" field null.
> * The **AgentMembership** and **AgentMembershipList** endpoints are only used for company-wide and group-specific access. That means that only `Agent` or `Group` type objects will be contained in the JSON response.
> * For device-specific access, the group has a value for the `agent` property that links it directly to the agent without using **AgentMembership**. This means that you have to create a new group for each agent that you want to assign that user to.
> * The `order` field is used to determine the order of the group types in the menu on the bottom left in the **Groups** section.
> * For **agent or asset device-specific groups**, the `agent` or `asset` fields will be filled in respectively. In our case the value is `null` since we do not have such groups. Additionally, the `name` field of the group will be `null`, and only the `name` field of `asset` or of `parent` and `type` will be filled in.\
>   **Important note**: these groups can be **created automatically** due to an underlying mechanism within the platform's code. They are **not intended for customers use**, as they do not offer any particular value to them and, for this reason, they can be filtered out in the code if needed.

## GroupList

| Verb                                                                                                               | Goal                                                                                                               | Required fields and IDs                                                                                            |
| :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_groups">GET</Anchor>          | Retrieves a list of groups and subgroups.                                                                          | You can use `?fields=name,type.*,agent.publicId,asset.publicId, parent.*,parent.type.*` to return the needed data. |
| <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_groups">PATCH</Anchor>    | Modifies one or more fields of one or more groups. If at least one field is added, the other two will be optional. | At least one among `name`, `type` and `parent`.                                                                    |
| <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_groups">POST</Anchor>       | Creates one or more new groups. Returns the `publicId` of each of the new groups.                                  | The `name` and `type` and their `publicId`.                                                                        |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_groups">DELETE</Anchor> | Deletes one or more new groups.                                                                                    | The `publicId` of the group(s) that will be deleted.                                                               |

**Please note**: the **Group** endpoint is the non-list version of **GroupList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_groups-publicid">GET</Anchor>, <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_groups-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_groups-publicid">DELETE</Anchor> actions for a single group. There is no POST verb available for this endpoint.

> ❗️ Important note about assigning groups
>
> **It is not possible to assign the company group as`parent` to a child `group` during POST or PATCH, as it will break the hierarchical tree graph.** Let's take the *Packaging Factory* customer group we have mentioned in previous examples: when the group was created with a POST request, the `name` and `type` were the only fields that were used. Even if the group does look like it is a child of *My Company* **graphically**, its `parent` value will actually be `null`.

## GroupTypeList

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Verb
      </th>

      <th>
        Goal
      </th>

      <th>
        Required fields and IDs
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_group-types">GET</Anchor>
      </td>

      <td>
        Retrieves a list of group types.
      </td>

      <td>
        You can use `?fields=*` to return the needed data.
      </td>
    </tr>

    <tr>
      <td>
        <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_group-types">PATCH</Anchor>
      </td>

      <td>
        Modifies one or more fields of one or more group types. If at least one field is added, the others will be optional.
      </td>

      <td>
        At least one among `name`, `description`, `order` and `color`.

        * _Note_*: an example of a string value for `color` can be `"#499c4a"`.
      </td>
    </tr>

    <tr>
      <td>
        <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_group-types">POST</Anchor>
      </td>

      <td>
        Creates one or more new group types. Returns the `publicId` of each of the new types.
      </td>

      <td>
        The `name` and its `publicId`.
      </td>
    </tr>

    <tr>
      <td>
        <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_group-types">DELETE</Anchor>
      </td>

      <td>
        Deletes one or more new group types.
      </td>

      <td>
        The `publicId` of the type(s) that will be deleted.
      </td>
    </tr>
  </tbody>
</Table>

> 👍 Additional fields
>
> The other available and optional fields to use for the creation of a group type are `description`, `order` and `color`. They are not mandatory since they allow the creation of a new group type even if a user does not possess the **Subgroups** module. If a user has it, the values of `order` and `color` will be set to the ones belonging to the first element in the group type list:
>
> <Image align="center" border={true} src="https://files.readme.io/695a90e3138e33cb158700981e99416a9a24b82267a5677a657067d50e551325-image.png" className="border" />

**Please note**: the **GroupType** endpoint is the non-list version of **GroupTypeList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_group-types-publicid">GET</Anchor>, <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_group-types-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_group-types-publicid">DELETE</Anchor> actions for a single group type. There is no POST verb available for this endpoint.

## GroupRoleList

| Verb                                                                                                            | Goal                                  | Required fields and IDs                                                                        |
| :-------------------------------------------------------------------------------------------------------------- | :------------------------------------ | :--------------------------------------------------------------------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_groups-roles">GET</Anchor> | Retrieves a list of roles in a group. | You can use `?fields=roles.*,roles.permissions.*,roles.audiences.*` to return the needed data. |

***

# Roles, access categories and permissions management

These endpoints handle the retrieval and manipulation of data belonging to **roles, access categories and permissions**.

## RoleList

| Verb                                                                                                              | Goal                                                                                                           | Required fields and IDs                                                                                                                                                   |
| :---------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_roles">GET</Anchor>          | Retrieves a list of roles in a company.                                                                        | You can use `?fields=name,description,enforce2fa, enforceSso,permissions.*,audiences.*` to return the needed data.                                                        |
| <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_roles">PATCH</Anchor>    | Modifies one or more fields of one or more roles. If at least one field is added, the others will be optional. | At least one among `name`, `description`, `enforce2fa` and `enforceSso`, `permissions` and their `publicId`, `audiences` and their `publicId`.                            |
| <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_roles">POST</Anchor>       | Creates one or more new roles. Returns the `publicId` of each of the new roles.                                | The `publicId`  of the role and  least one among `name`, `description`, `enforce2fa`, `enforceSso`, `permissions` and their `publicId`, `audiences` and their `publicId`. |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_roles">DELETE</Anchor> | Deletes one or more new roles.                                                                                 | The `publicId` of the role(s) that will be deleted.                                                                                                                       |

**Please note**: the **Role** endpoint is the non-list version of **RoleList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_roles-publicid">GET</Anchor>, <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_roles-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_roles-publicid">DELETE</Anchor> actions for a single role. There is no POST verb available for this endpoint.

> 🚧 Notes about fields in RoleList
>
> * *Platform administrator* is a **default** role, therefore only the `name` can be changed;
> * *Category A* is a **default** access category, and the `default` field value will always be true.

## AudienceList

| Verb                                                                                                                  | Goal                                                                                                                      | Required fields, IDs or query params                                                       |
| :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_audiences">GET</Anchor>          | Retrieves a list of access categories.                                                                                    | You can use `?fields=description,name,default,type` to return the needed data.             |
| <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_audiences">POST</Anchor>       | Creates one or more new access categories. Returns the `publicId` of each of the new ones.                                | The `name` you want to give to the access category.                                        |
| <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_audiences">PATCH</Anchor>    | Modifies one or more fields of one or more access categories. If at least one field is added, the other will be optional. | The `publicId`  of the access category and at  least one between `name` and `description`. |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_audiences">DELETE</Anchor> | Deletes one or more new access categories.                                                                                | The `publicId` of the access category that will be deleted.                                |

**Please note**: the **Audience** endpoint is the non-list version of **AudienceList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_roles-publicid">GET</Anchor>, <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_roles-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_roles-publicid">DELETE</Anchor> actions for a single access category. There is no POST verb available for this endpoint.

## PermissionList

| Verb                                                                                                           | Goal                             | Required fields, IDs or query params |
| :------------------------------------------------------------------------------------------------------------- | :------------------------------- | :----------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_permissions">GET</Anchor> | Retrieves a list of permissions. | N/A                                  |

> 👍 Notes about permissions
>
> * If the value `COMPANY_WIDE_ROLE` is NOT present in the `permissions` array, then that role is a **group/device** specific role;
> * The permissions retrieved by this endpoint are all **default**. It is not possible to create custom permissions.

***

# User management

These endpoints handle the retrieval and manipulation of data concerning **users**.

## UserList

| Verb                                                                                                              | Goal                           | Required fields and IDs                                                          |
| :---------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_users">GET</Anchor>          | Retrieves a list of users.     | You can use `?fields=*,memberships.*,otpauthRequired` to return the needed data. |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_users">DELETE</Anchor> | Deletes one or more new users. | The `publicId` of the user(s) that will be deleted.                              |

**Please note**:

* If a user received an unlimited time invite, then the `expiresOn` field will be `null`. Additionally, `otpauthRequired` will only be `true` if a user uses 2FA for the IXON Portal.
* The **User** endpoint is the non-list version of **UserList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_users-publicid">GET</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_users-publicid">DELETE</Anchor> actions for a single access category.

> ❗️ UserList - POST
>
> **UserList** owns a POST verb as well: its purpose is to create a user only when said user has been **invited to a company by another user**. *Since this action is performed through the interface of the portal, we advise against its use.*

***

# Membership management

These endpoints handle the retrieval and manipulation of data concerning **memberships**. In case you do not know what they are, please check <Anchor label="this section" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/user-access-structure-explained">this section</Anchor>.

## AgentMembershipList

| Verb                                                                                                                           | Goal                                                                                       | Required fields and IDs                                                       |
| :----------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_agents-memberships">GET</Anchor>          | Retrieves a list of agent memberships.                                                     | You can use `?fields=*,agent.*,group.*` to return the needed data.            |
| <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_agents-memberships">POST</Anchor>       | Creates one or more new agent memberships. Returns the `publicId` of each of the new ones. | The `publicId` of both the `agent` and the `group` you want to assign to it.  |
| <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_agents-memberships">PATCH</Anchor>    | Modifies one or more fields of one or more agent memberships.                              | The `publicId`  of both the `agent` and the `group` you want to assign to it. |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_agents-memberships">DELETE</Anchor> | Deletes one or more new access categories.                                                 | The `publicId` of the agent membership(s) that will be deleted.               |

**Please note**: the **AgentMembership** endpoint is the non-list version of **AgentMembershipList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_agents-memberships-publicid">GET</Anchor>, <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_agents-memberships-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_agents-memberships-publicid">DELETE</Anchor> actions for a single access category. There is no POST verb available for this endpoint.

## UserMembershipList

| Verb                                                                                                                          | Goal                                                                                      | Required fields and IDs                                                                                                                                                                                             |
| :---------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_users-memberships">GET</Anchor>          | Retrieves a list of user memberships.                                                     | You can use `?fields=user.*,invite.*,group.*,role.*,expiresOn` to return the needed data.                                                                                                                           |
| <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_users-memberships">POST</Anchor>       | Creates one or more new user memberships. Returns the `publicId` of each of the new ones. | The `publicId` of both the `group` and the `role` you want to assign the user to, and the `publicId` of either the `user` or the `invite`. If neither of these last two fields are used, you will receive an error. |
| <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_users-memberships">PATCH</Anchor>    | Modifies one or more fields of one or more user memberships.                              | The `publicId`  of the membership and the `group`, `role` or `expiresOn` that you want to modify.                                                                                                                   |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_users-memberships">DELETE</Anchor> | Deletes one or more new user memberships.                                                 | The `publicId` of the user membership(s) that will be deleted.                                                                                                                                                      |

**Please note**: the **UserMembership** endpoint is the non-list version of **UserMembershipList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_users-memberships-publicid">GET</Anchor>, <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_users-memberships-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_users-memberships-publicid">DELETE</Anchor> actions for a single access category. There is no POST verb available for this endpoint.

> ❗️ UserMembershipUserList - PUT
>
> In **Admin > User management > Users** it is possible to edit users by clicking on the pencil icon on the right-end side of a user's section. This endpoint is called when clicking on "Confirm" after performing any type of change. *Since these changes can mainly be performed through the interface of the portal, we advise against its use.*

***

# Invite management

These endpoints handle the retrieval and manipulation of data concerning **invites**.

## InviteList

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Verb
      </th>

      <th>
        Goal
      </th>

      <th>
        Required fields and IDs
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_invites">GET</Anchor>
      </td>

      <td>
        Retrieves a list of existing invites.
      </td>

      <td>
        You can use `?fields=*,memberships.*` to return the needed data.
      </td>
    </tr>

    <tr>
      <td>
        <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_invites">POST</Anchor>
      </td>

      <td>
        Creates one or more new invites. Returns either an error or success response.
      </td>

      <td>
        The `emailAddress` of the user you want to invite and the `publicId` of both the `group` and the `role` you want to invite them to (inside `groupRoles`).

        * _Note_*: `Api-Branding` is a mandatory header and its default value is `portal.ixon.cloud`.
      </td>
    </tr>

    <tr>
      <td>
        <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_invites">DELETE</Anchor>
      </td>

      <td>
        Deletes one or more new user invites.
      </td>

      <td>
        The `publicId` of the invite(s) that will be deleted.
      </td>
    </tr>
  </tbody>
</Table>

**Please note**: the **Invite** endpoint is the non-list version of **InviteList**, and can be used to perform <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_invites-publicid">GET</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_invites-publicid">DELETE</Anchor> actions for a single invite. There is no POST verb available for this endpoint.

## InviteResendList

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Verb
      </th>

      <th>
        Goal
      </th>

      <th>
        Required fields and IDs
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_invites-resend">POST</Anchor>
      </td>

      <td>
        Resends invites to one or more users. Returns either an error or success response.
      </td>

      <td>
        The `publicId` of the existing invite(s).

        * _Note_*: `Api-Branding` is a mandatory header and its default value is `portal.ixon.cloud`.
      </td>
    </tr>
  </tbody>
</Table>

**Please note**: the **InviteResend** endpoint is the non-list version of **InviteResendList**, and can be used to perform a <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_invites-publicid-resend">POST</Anchor> action for a single invite.

> ❗️ InviteFinish - POST
>
> This endpoint is used to conclude the invitation process the user is redirected to through the invitation email, and it's called by pressing the **Accept invitation button**, which can be pressed after reading and accepting the terms of use. *Since this action can mainly be performed through the invitation email, we advise against its use.*
>
> <Image align="center" width="400px" src="https://files.readme.io/007aacaa26d75aae99e945445d1326fc2311704beedbb42e97dcc0b3577ea464-image.png" />

***

# How-tos and use cases

This section provides practical, step-by-step guides for common tasks performed on the portal, demonstrating how to use our API endpoints together to achieve a specific outcome. Real use case examples will be provided along the way.

## How to create a new group and then assign it to a device

**Goal**: create a new group called *Headquarters Testers* belonging to the *General Testing* type, and assign it to the *Box Grabber* machine.

**What you will need**:

* The `publicId` of the group **type** you will assign to the new group.
* The `publicId` of the **agent** you wish to link the group to.
* The `publicId` of the new **group** that will be linked to the agent.

### Step 1 - Create the new group type

Since we do not yet possess this group type, we will need to create it using the **<Anchor label="POST Request" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/grouptypelist">POST Request</Anchor>** of the **GroupTypeList** endpoint and the following body parameters:

```curl POST Request
curl --location 'https://portal.ixon.cloud/api/group-types' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken' \
--data '
[
  {
    "name": "General Testing",
    "description": "General test group."
  }
]
'
```
```json Response
{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newGroupTypePublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}
```

### Step 2 - Create the new group

After retrieving the `publicId` of the new *General Testing* group type, you can create a new group by using the <Anchor label="**POST Request**" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/grouplist">**POST Request**</Anchor> of the **GroupList** endpoint. This group is not a subgroup, so it does not need a `parent` field in its request body:

```curl POST Request
curl --location 'https://portal.ixon.cloud/api/groups' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken' \
--data '[
  {
    "type": {
      "publicId": "$newGroupTypePublicId"
    },
    "name": "Headquarters Testers"
    }
]'
```
```json Response
{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newGroupPublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}
```

### Step 3 - Create a new agent membership

As stated at the beginning of the article, an agent membership consists of assigning a group to a device. To retrieve an agent's ID, follow the instructions in this <Anchor label="knowledge article" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-prerequisites#how-to-get-an-agents-id">knowledge article</Anchor>. After retrieving it, all we need to do now is use the **agent's ID** and **group's ID** we obtained in Step 2 to link our new group to a device by calling an **AgentMembershipList <Anchor label="POST Request" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/agentmembershiplist">POST Request</Anchor>**:

```curl POST Request
curl --location 'https://portal.ixon.cloud/api/agents/memberships' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken' \
--data '
[
  {
    "agent": {
      "publicId": "$agentPublicId"
    },
    "group": {
      "publicId": "$newGroupPublicId"
    }
  }
]
'
```
```json Response
{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$membershipPublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}
```

After these steps, we can navigate to **Fleet Manager > Devices > Box Grabber (or device of choice)** and see that we have successfully linked our group to the machine:

![](https://files.readme.io/d3c3fde1048496cbe84639af2bea13852ec92362aad81677c2524b4b70839937-image.png)

## How to create a new access category and assign it to a new role

**Goal**: create a new access category called *VPN Box Grabber* and assign it to the *VPN General Testing* role, which we will create as a **device-specific role**.

**What you will need**:

* The `publicId` of the new access category that you will assign to the role.
* The `publicId` of the permission that we want to give to the role.

### Step 1 - Create the new access category

We will use the **AudienceList <Anchor label="POST Request" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/audiencelist">POST Request</Anchor>** to create a new access category. Since we are using it to manage a VPN Access, it will be of "service" type:

```curl POST Request
curl --location 'https://portal.ixon.cloud/api/audiences' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken' \
--data '
[
  {
    "name": "VPN Box Grabber",
    "type": "service"
  }
]
'
```
```json Response
{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newAccessCategoryId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}
```

**Note**: the `description` field you might find in the endpoint web-page is not used and it will have no effect on the interface in the Portal. Therefore, we recommend omitting it.

### Step 2 - Get the list of possible permissions

Before creating a new role, we will need to retrieve the default list of permissions available via a **<Anchor label="GET Request" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/permissionlist">GET Request</Anchor>** of **PermissionList**:

```curl GET Request
curl --location 'https://portal.ixon.cloud/api/permissions' \
--header 'Api-Version: 2' \
--header 'accept: application/json'
```
```json Response
{
  "type": "Permission",
  "data": [
    {
      "publicId": "APPROVE_ACCESS_REQUESTS"
    },
    {
      "publicId": "COMPANY_ADMIN"
    },
    {
      "publicId": "COMPANY_WIDE_ROLE"
    },
    {
      "publicId": "DEVELOP_APP"
    },
    {
      "publicId": "MANAGE_AGENT"
    },
    {
      "publicId": "MANAGE_AGENT_TEMPLATE"
    },
    {
      "publicId": "MANAGE_APP"
    },
    {
      "publicId": "MANAGE_ASSET_LIBRARY"
    },
    {
      "publicId": "MANAGE_BRANDING"
    },
    {
      "publicId": "MANAGE_COMPANY"
    },
    {
      "publicId": "MANAGE_GROUP"
    },
    {
      "publicId": "MANAGE_LICENCE"
    },
    {
      "publicId": "MANAGE_PAGE"
    },
    {
      "publicId": "MANAGE_USER"
    },
    {
      "publicId": "NOTIFY_EXPIRING_LICENCE"
    },
    {
      "publicId": "TRANSFER_AGENT"
    },
    {
      "publicId": "VIEW_AUDIT_LOGS"
    }
  ],
  "moreAfter": null,
  "status": "success"
}
```

In our case, we will choose `MANAGE_AGENT` since the role will be device-specific. This value corresponds to the *Manage devices* option found in **Admin > Roles > Add new role > Devices**.

### Step 3 - Create the new role

After obtaining the `publicId` of the new access category and of the permission we need, we can create the new role that we will assign it to by using the **<Anchor label="POST Request" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/rolelist">POST Request</Anchor>** of the **RoleList** endpoint:

```curl POST Request
curl --location 'https://portal.ixon.cloud/api/roles' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken' \
--data '
[
  {
    "name": "VPN General Testing",
    "description": "Role for generic VPN Testing.",
    "enforce2fa": false,
    "enforceSso": false,
    "permissions": [
      {
        "publicId": "MANAGE_AGENT"
      }
    ],
    "audiences": [
      {
        "publicId": "$newAccessCategoryPublicId"
      }
    ]
  }
]
'
```
```json Response
{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$rolePublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}
```

In this case, we decided to not enforce 2FA or SSO, therefore their values are false. We can now visualize the new role in **Admin > Roles**:

<Image align="center" width="300px" src="https://files.readme.io/e9ef9d4077458c7673dae1aff68a94dbdcccf379e0e8fc24d49bdc7d8cd47c14-image.png" />

## How to invite a user to your company

**Goal**: inviting a new user to the company and assign them to the *General Testing* group with a *VPN General Testing* role.

**What you will need**:

* The `publicId` of the role you want to assign to the user.
* The `publicId` of the group you want to assign the user to.
* The user's `emailAddress`.

### Step 1 - Retrieve the group and role public IDs

You can refer to these previous *How-tos* sections to retrieve the <Anchor label="group ID" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/how-to-create-a-new-group-and-then-assign-it-to-a-device">group ID</Anchor> and the <Anchor label="role ID" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/how-to-create-a-new-access-category-and-assign-it-to-a-new-role">role ID</Anchor> respectively. When you have the necessary *publicIds*, you can proceed to the next step.

### Step 2 - Invite the user

Assuming that we have the email of the user we want to invite, we can do so by using the <Anchor label="**POST Request**" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/invitelist">**POST Request**</Anchor> of the **InviteList** endpoint. It is important to note that the **required Api-Branding header** should contain the URL of your company. The default is **portal.ixon.cloud**, but the entered URL should be different if you use *White Label Premium*. It is also possible to include a `message` field:

```curl POST Request
curl --location 'https://portal.ixon.cloud/api/invites' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Api-Branding: portal.ixon.cloud' \
--header 'Authorization: Bearer $bearerToken' \
--data-raw '
[
  {
    "emailAddress": "tester1@example.com",
    "message": "You have been invited to the company.",
    "groupRoles": [
      {
        "group": {
          "publicId": "$groupPublicId"
        },
        "role": {
          "publicId": "$rolePublicId"
        }
      }
    ]
  }
]
'
```
```json Response
{
    "type": "InviteResponse",
    "data": {
        "invites": [
            {
                "publicId": "$invitePublicId"
            }
        ],
        "userMemberships": [
            {
                "publicId": "$userMembershipPublicId"
            }
        ]
    },
    "status": "success"
}
```

As you can see, the response will return the `publicId` of the invite and that of the `userMembership` that was applied. An email with the invite link will be sent to the entered email address. That person can create an account to the IXON Cloud by clicking on the displayed link if they currently do not have an IXON Cloud account.

## How to get a list of users

**Goal**: retrieving a list of users to keep in your company in your own administration.

**What you will need**: standard headers (`applicationId`, `companyId`, `bearerToken`).

To obtain a list of users you only have to follow one single step consisting of sending a <Anchor label="**GET request**" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/userlist">**GET request**</Anchor> to the **UserList** endpoint:

```curl GET Request
curl --location 'https://portal.ixon.cloud/api/users?fields=publicId,name,emailAddress,lastSeenOn%,memberships.*,otpauthRequired' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken'
```
```json Response
{
  "type": "User",
  "data": [
    {
      "publicId": "$userPublicId",
      "name": "User 1",
      "emailAddress": "user1@example.com",
      "lastSeenOn": "2025-08-06T11:23:57Z",
      "memberships": [
        {
          "publicId": "$userMembership",
          "expiresOn": null
        }
      ],
      "otpauthRequired": true
    },
    {
      "publicId": "$userPublicId",
      "name": "User 2",
      "emailAddress": "user2@example.com",
      "lastSeenOn": "2025-08-06T11:35:03Z",
      "memberships": [
        {
          "publicId": "$userMembershipPublicId",
          "expiresOn": null
        },
        {
          "publicId": "$userMembershipPublicId",
          "expiresOn": "2025-08-06T21:48:00Z"
        }
      ],
      "otpauthRequired": false
    },
    {
      "publicId": "$userPublicId",
      "name": "User 3",
      "emailAddress": "user3@example.com",
      "lastSeenOn": "2025-08-06T07:43:44Z",
      "memberships": [
        {
          "publicId": "$userMembershipPublicId",
          "expiresOn": null
        },
        {
          "publicId": "$userMembershipPublicId",
          "expiresOn": "2025-08-06T21:48:00Z"
        }
      ],
      "otpauthRequired": true
    }
  ],
  "moreAfter": null,
  "status": "success"
}
```

## How to remove a user

**Goal**: removing a user from your company.

**What you will need**:

* The `publicId` of the **user** you want to remove.

The **UserList** endpoint can be used to remove one or multiple users as well. Assuming that you have obtained the user ID with the **GET request** in the example above, you now have to use it in the <Anchor label="**DELETE request**" target="_blank" href="https://developer.ixon.cloud/docs/manage-groups-users-roles-and-more#/userlist">**DELETE request**</Anchor>:

```curl DELETE Request
curl --location 'https://portal.ixon.cloud/api/users' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'Authorization: Bearer $bearerToken'
--data '
[
  {
    "publicId": "$userPublicId"
  }
]'
```
```json Response
{
    "type": "Null",
    "data": null,
    "status": "success"
}
```