Manage users

The management of users can be integrated in custom applications by using the APIv2. 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 requested the basic information headers , 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 support article 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 Admin > Licenses. 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:

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

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:
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:
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:

👍
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:

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:

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:

This section is found in **Fleet Manager > Devices** when a device of choice is selected. The action of "adding a group" **creates the membership**, making it so that a device is "subscribed" 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.

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 Admin > User management > Groups;
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 Admin > User management > Users;
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:

In Admin > User management > Users, when selecting "Edit user" (or "Invite User") and then on the "+" 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.
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 support article;
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:

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.

Diagram explanation

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

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 sections of this article.

Group management

🚧
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;

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.

GroupList

GET

Returns a list of groups and subgroups:

curl --location 'https://portal.ixon.cloud/api/groups?fields=name,type.*,agent.publicId,asset.publicId,parent.*,parent.type.*' \
--header 'Api-Version: 2' \
--header 'Api-Application: $application_id' \
--header 'Api-Company: $company_id' \
--header 'accept: application/json' \
--header 'Authorization: Bearer $bearer_token'

{
  "type": "Group",
  "data": [
    {
      "publicId": "$companyGroupPublicId",
      "name": "My Company",
      "type": null,
      "agent": null,
      "asset": null,
      "parent": null
    },
    {
      "publicId": "$groupPublicId",
      "name": "Customer 1",
      "type": {
        "publicId": "$typePublicId",
        "name": "Customer",
        "description": null,
        "order": 0,
        "color": "#6e40aa"
      },
      "agent": null,
      "asset": null,
      "parent": {
        "publicId": "$parentGroupPublicId",
        "name": "Packaging Factories",
        "type": {
          "publicId": "$typePublicId",
          "name": "Customer",
          "description": null,
          "order": 0,
          "color": "#6e40aa"
        }
      }
    },
    {
      "publicId": "$groupPublicId",
      "name": "Customer 2",
      "type": {
        "publicId": "$typePublicId",
        "name": "Customer",
        "description": null,
        "order": 0,
        "color": "#6e40aa"
      },
      "agent": null,
      "asset": null,
      "parent": {
        "publicId": "$parentGroupPublicId",
        "name": "Packaging Factories",
        "type": {
          "publicId": "$typePublicId",
          "name": "Customer",
          "description": null,
          "order": 0,
          "color": "#6e40aa"
        }
      }
    },
    {
      "publicId": "$groupPublicId",
      "name": "Customer 3",
      "type": {
        "publicId": "$typePublicId",
        "name": "Customer",
        "description": null,
        "order": 0,
        "color": "#6e40aa"
      },
      "agent": null,
      "asset": null,
      "parent": {
        "publicId": "$parentGroupPublicId",
        "name": "Packaging Factories",
        "type": {
          "publicId": "$typePublicId",
          "name": "Customer",
          "description": null,
          "order": 0,
          "color": "#6e40aa"
        }
      }
    },
    {
      "publicId": "$groupPublicId",
      "name": "Customer 4",
      "type": {
        "publicId": "$typePublicId",
        "name": "Customer",
        "description": null,
        "order": 0,
        "color": "#6e40aa"
      },
      "agent": null,
      "asset": null,
      "parent": {
        "publicId": "$parentGroupPublicId",
        "name": "Packaging Factories",
        "type": {
          "publicId": "$typePublicId",
          "name": "Customer",
          "description": null,
          "order": 0,
          "color": "#6e40aa"
        }
      }
    },
    {
      "publicId": "$groupPublicId",
      "name": "P. E. Testing",
      "type": {
        "publicId": "$typePublicId",
        "name": "Partner",
        "description": null,
        "order": 1000,
        "color": "#499c4a"
      },
      "agent": null,
      "asset": null,
      "parent": {
        "publicId": "$parentGroupPublicId",
        "name": "Propack Engineering",
        "type": {
          "publicId": "$typePublicId",
          "name": "Partner",
          "description": null,
          "order": 1000,
          "color": "#499c4a"
        }
      }
    },
    {
      "publicId": "$groupPublicId",
      "name": "Propack Engineering",
      "type": {
        "publicId": "$typePublicId",
        "name": "Partner",
        "description": null,
        "order": 1000,
        "color": "#499c4a"
      },
      "agent": null,
      "asset": null,
      "parent": null
    },
    {
      "publicId": "$groupPublicId",
      "name": "Packaging Factories",
      "type": {
        "publicId": "$typePublicId",
        "name": "Customer",
        "description": null,
        "order": 0,
        "color": "#6e40aa"
      },
      "agent": null,
      "asset": null,
      "parent": null
    }
  ],
  "moreAfter": null,
  "status": "success"
}

A few things to note:

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.

POST

Creates one or more new groups (only type and name are required fields):

curl --location 'https://portal.ixon.cloud/api/groups' \
--header 'Api-Version: 2' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '[
  {
    "type": {
      "publicId": "$groupTypePublicId"
    },
    "parent": {
      "publicId": "$parentGroupPublicId"
    },
    "name": "Customer 5"
  }
]'

{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newGroupPublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

PATCH

Modifies a group's name (always required), type or parent (both optional). Here is an example where we select an existing group and change its name, type and parent:

curl --location --request PATCH 'https://portal.ixon.cloud/api/groups' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'Authorization: Bearer $bearerToken' \
--data '
[
  {
    "type": {
      "publicId": "$groupTypePublicId"
    },
    "parent": {
      "publicId": "$parentGroupPublicId"
    },
    "publicId": "$groupPublicId",
    "name": "P. E. Production"
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

DELETE

Deletes one or more groups at the same time:

curl --location --request DELETE 'https://portal.ixon.cloud/api/groups' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
		--header 'Authorization: Bearer $bearerToken' \
     --data '
[
  {
    "publicId": "$groupPublicId"
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

Please note: the Group endpoint is the non-list version of GroupList, and can be used to perform GET, PATCH and DELETE actions for a single group. There is no POST verb available for this endpoint.

GroupTypeList

GET

Returns a list of group types:

curl --location 'https://portal.ixon.cloud/api/group-types?fields=*' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'Authorization: Bearer $bearerToken'

{
    "type": "GroupType",
    "data": [
        {
            "publicId": "$groupTypeId",
            "name": "Customer",
            "description": null,
            "order": 0,
            "color": "#6e40aa"
        },
        {
            "publicId": "$groupTypeId",
            "name": "Partner",
            "description": null,
            "order": 1000,
            "color": "#499c4a"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

POST

Creates one or more group types:

curl --location 'https://portal.ixon.cloud/api/group-types' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "name": "Support"
  }
]
'

{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newGroupTypePublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

Please note: 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:

PATCH

Modifies one or more group types. In this example we only want to change the group type's description:

curl --location --request PATCH 'https://portal.ixon.cloud/api/group-types' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'Authorization: Bearer $bearerToken' \
--data '
[
  {
    "publicId": "$groupTypePublicId",
    "description": "This group type is for customers."
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

Please note: apart from the description, the other optional and modifiable fields are name, order and color.

DELETE

Deletes one or more group types:

curl --location --request DELETE 'https://portal.ixon.cloud/api/group-types' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "publicId": "$groupTypePublicId"
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

Please note: the GroupType endpoint is the non-list version of GroupTypeList, and can be used to perform GET, PATCH and DELETE actions for a single group type. There is no POST verb available for this endpoint.

GroupRoleList

GET

Returns a list of possible roles a user may give in a specific group:

curl --location 'https://portal.ixon.cloud/api/groups/roles?fields=roles.*%2Croles.permissions.*%2Croles.audiences.*' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \

{
    "type": "GroupRole",
    "data": [
        {
            "group": null,
            "roles": [
                {
                    "publicId": "$rolePublicId",
                    "name": "Platform administrator",
                    "description": "This role is default, only the name can be changed. It is not possible to remove the last user with this role",
                    "enforce2fa": false,
                    "enforceSso": false,
                    "permissions": [
                        {
                            "publicId": "APPROVE_ACCESS_REQUESTS"
                        },
                        {
                            "publicId": "COMPANY_ADMIN"
                        },
                        {
                            "publicId": "NOTIFY_EXPIRING_LICENCE"
                        }
                    ],
                    "audiences": [
                        {
                            "publicId": "$accessCategoryPublicId",
                            "name": "HTTP Admin",
                            "description": "HTTP Admin access only.!",
                            "default": false,
                            "type": "service"
                        },
                        {
                            "publicId": "$accessCategoryPublicId",
                            "name": "VPN",
                            "description": "VPN access only.",
                            "default": false,
                            "type": "service"
                        },
                        {
                            "publicId": "$accessCategoryPublicId",
                            "name": "Category A",
                            "description": null,
                            "default": true,
                            "type": null
                        }
                    ]
                },
                {
                    "publicId": "$rolePublicId",
                    "name": "Engineer",
                    "description": null,
                    "enforce2fa": false,
                    "enforceSso": false,
                    "permissions": [
                        {
                            "publicId": "COMPANY_WIDE_ROLE"
                        },
                        {
                            "publicId": "MANAGE_AGENT"
                        },
                        {
                            "publicId": "MANAGE_AGENT_TEMPLATE"
                        },
                        {
                            "publicId": "MANAGE_GROUP"
                        },
                        {
                            "publicId": "MANAGE_LICENCE"
                        },
                        {
                            "publicId": "MANAGE_PAGE"
                        },
                        {
                            "publicId": "MANAGE_USER"
                        },
                        {
                            "publicId": "VIEW_AUDIT_LOGS"
                        }
                    ],
                    "audiences": [
                        {
                            "publicId": "$accessCategoryPublicId",
                            "name": "Category A",
                            "description": null,
                            "default": true,
                            "type": null
                        }
                    ]
                },
                {
                    "publicId": "$rolePublicId",
                    "name": "Secure Edge/IXrouter VPN/HTTP Access",
                    "description": null,
                    "enforce2fa": false,
                    "enforceSso": false,
                    "permissions": [],
                    "audiences": [
                        {
                            "publicId": "$accessCategoryPublicId",
                            "name": "VPN",
                            "description": null,
                            "default": false,
                            "type": "service"
                        },
                        {
                            "publicId": "$accessCategoryPublicId",
                            "name": "HTTP User",
                            "description": null,
                            "default": false,
                            "type": "service"
                        }
                    ]
                }
            ]
        }
    ],
    "moreAfter": null,
    "status": "success"
}

👍
Note about permissions
In the example above, the Engineer role has a COMPANY_WIDE_ROLE permission, allowing access . If this value is NOT present in the permissions array, then that role is a group/device specific role.

Role, access categories and permissions management

RoleList

GET

Returns a list of roles in a company:

curl --location 'https://portal.ixon.cloud/api/roles?fields=name,description,enforce2fa,enforceSso,permissions.*,audiences.*' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \

{
  "type": "Role",
  "data": [
    {
      "publicId": "$rolePublicId",
      "name": "Engineer",
      "description": "Engineer role for maintenance.",
      "enforce2fa": false,
      "enforceSso": false,
      "permissions": [
        {
          "publicId": "COMPANY_WIDE_ROLE"
        },
        {
          "publicId": "MANAGE_AGENT"
        },
        {
          "publicId": "MANAGE_AGENT_TEMPLATE"
        },
        {
          "publicId": "MANAGE_GROUP"
        },
        {
          "publicId": "MANAGE_LICENCE"
        },
        {
          "publicId": "MANAGE_PAGE"
        },
        {
          "publicId": "MANAGE_USER"
        },
        {
          "publicId": "VIEW_AUDIT_LOGS"
        }
      ],
      "audiences": [
        {
          "publicId": "$accessCategoryPublicId",
          "name": "Category A",
          "description": null,
          "default": true,
          "type": null
        }
      ]
    },
    {
      "publicId": "$rolePublicId",
      "name": "Platform administrator",
      "description": "This role is default, only the name can be changed. It is not possible to remove the last user with this role",
      "enforce2fa": false,
      "enforceSso": false,
      "permissions": [
        {
          "publicId": "APPROVE_ACCESS_REQUESTS"
        },
        {
          "publicId": "COMPANY_ADMIN"
        },
        {
          "publicId": "NOTIFY_EXPIRING_LICENCE"
        }
      ],
      "audiences": [
        {
          "publicId": "$accessCategoryPublicId",
          "name": "HTTP Admin",
          "description": null,
          "default": false,
          "type": "service"
        },
        {
          "publicId": "$accessCategoryPublicId",
          "name": "HTTP User",
          "description": null,
          "default": false,
          "type": "service"
        },
        {
          "publicId": "$accessCategoryPublicId",
          "name": "Dashboard/Pages",
          "description": null,
          "default": false,
          "type": "page"
        },
        {
          "publicId": "$accessCategoryPublicId",
          "name": "Category A",
          "description": null,
          "default": true,
          "type": null
        }
      ]
    }
  ],
  "moreAfter": null,
  "status": "success"
}

Please note:

Platform administrator is a default role, and as the description field says, only the name can be changed;
Category A is a default access category, and the default field value will always be true.

POST

Creates one or multiple new roles. In this case, we will create a new role for generic testing with a COMPANT_WIDE_ROLE permission and a Category A type of access category:

curl --location 'https://portal.ixon.cloud/api/roles' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "name": "Generic Tester",
    "description": "Role for generic testing of machines.",
    "enforce2fa": false,
    "enforceSso": false,
    "permissions": [
      {
        "publicId": "COMPANY_WIDE_ROLE"
      }
    ],
    "audiences": [
      {
        "publicId": "$accessCategoryPublicId"
      }
    ]
  }
]
'

{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newRolePublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

PATCH

Modifies one or more fields of one or multiple roles. In this case, we will modify the name and the description of a single role:

curl --location --request PATCH 'https://portal.ixon.cloud/api/roles' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "publicId": "$rolePublicId",
    "name": "Bottling machine tester",
    "description": "A role for bottling machine testers."
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

DELETE

Deletes one or more roles:

curl --location --request DELETE 'https://portal.ixon.cloud/api/roles' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "publicId": "BrK9JhbDR1LZ"
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

Please note: the Role endpoint is the non-list version of RoleList, and can be used to perform GET, PATCH and DELETE actions for a single role. There is no POST verb available for this endpoint.

AudienceList

GET

Retrieves a list of access categories:

curl --location 'https://portal.ixon.cloud/api/audiences?fields=description%2Cname%2Cdefault%2Ctype' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \

{
    "type": "Audience",
    "data": [
        {
            "publicId": "$accessCategoryPublicId",
            "name": "HTTP Admin",
            "description": null,
            "default": false,
            "type": "service"
        },
        {
            "publicId": "$accessCategoryPublicId",
            "name": "VPN",
            "description": null,
            "default": false,
            "type": "service"
        },
        {
            "publicId": "$accessCategoryPublicId",
            "name": "HTTP User",
            "description": null,
            "default": false,
            "type": "service"
        },
        {
            "publicId": "$accessCategoryPublicId",
            "name": "Dashboard/Pages",
            "description": null,
            "default": false,
            "type": "page"
        },
        {
            "publicId": "$accessCategoryPublicId",
            "name": "Category A",
            "description": null,
            "default": true,
            "type": null
        }
    ],
    "moreAfter": null,
    "status": "success"
}

POST

Creates one or more access categories:

curl --location 'https://portal.ixon.cloud/api/audiences' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
     --data '
[
  {
    "name": "Bottling machine HTTP service",
    "description": "Access to the bottling machine dashboard.",
    "type": "service"
  }
]
'

{
    "type": "CreateResponse",
    "data": [
        {
            "publicId": "$newAccessCategoryPublicId"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

PATCH

Modifies one or more access categories. In this case we will modify the name and description:

curl --location --request PATCH 'https://portal.ixon.cloud/api/audiences' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "publicId": "$accessCategoryPublicId",
    "name": "Packing machine HTTP service",
    "description": "Access to the packing machine dashboard."
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

DELETE

Deletes one or more access categories:

curl --location --request DELETE 'https://portal.ixon.cloud/api/audiences' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \
--data '
[
  {
    "publicId": "$accessCategoryPublicId"
  }
]
'

Please note: the Audience endpoint is the non-list version of AudienceList, and can be used to perform GET, PATCH and DELETE actions for a single access category. There is no POST verb available for this endpoint.

AudienceAgentReferenceList

GET

Retrieves multiple access categories related to multiple agents:

curl --location 'https://portal.ixon.cloud/api/audiences/agent' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \

{
    "type": "AudienceAgentReference",
    "data": [
        {
            "publicId": "$agentPublicId",
            "name": "Packaging Machine",
            "assets": [],
            "audiences": [
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                }
            ]
        },
        {
            "publicId": "$agentPublicId",
            "name": "Rebecca's Secure Edge Pro",
            "assets": [],
            "audiences": [
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                },
                {
                    "publicId": "$accessCategoryPublicId",
                    "reference": {
                        "name": "Audience"
                    }
                }
            ]
        }
    ],
    "moreAfter": null,
    "status": "success"
}

AudienceAssetReferenceList

GET

Retrieves multiple access categories related to multiple assets:

curl --location 'https://portal.ixon.cloud/api/audiences/asset' \
--header 'Api-Application: $applicationId' \
--header 'Api-Company: $companyId' \
--header 'Api-Version: 2' \
--header 'accept: application/json' \
--header 'authorization: Bearer $bearerToken' \

{
  "type": "AudienceAssetReference",
  "data": [
    {
      "publicId": "$subassetPublicId",
      "name": "Crack detector",
      "agent": null,
      "root": {
        "publicId": "$mainAssetPublicId",
        "reference": {
          "name": "Asset"
        }
      },
      "audiences": []
    },
    {
      "publicId": "$subassetPublicId",
      "name": "Color Detector",
      "agent": null,
      "root": {
        "publicId": "$mainAssetPublicId",
        "reference": {
          "name": "Asset"
        }
      },
      "audiences": []
    },
    {
      "publicId": "$assetPublicId",
      "name": "GPS simulation",
      "agent": {
        "publicId": "$agentPublicId",
        "reference": {
          "name": "Agent"
        }
      },
      "root": null,
      "audiences": [
        {
          "publicId": "$audiencePublicId",
          "reference": {
            "name": "Audience"
          }
        }
      ]
    }
  ],
  "moreAfter": null,
  "status": "success"
}

Please note: as you can see, it is possible to retrieve a sub-asset that belongs to another asset, which will be placed in the root field. In case the asset belongs to an agent, the root field will be null.

User management

To comply with IXONs new user management system, you first need to get the ID's for the role and group you'd like to add a new user to. You can do that using the following request for the role ID using the RoleList endpoint.

curl --request GET \
     --url '<<url>>:443/api/roles?fields=publicId,name' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

To obtain a group ID, you have to use the following request. When you want to assign a user to a company wide role, which has access to all devices you have to use the company group, of which te group ID will be included in the response. The endpoint is GroupList.

curl --request GET \
     --url '<<url>>:443/api/groups?fields=publicId,name' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

Invite a user

Now that you have the role ID and group ID, you can send the POST request to the InviteList endpoint to invite a new user. Below you can find an example of how that request should look. The 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.

You also have to include a data field with the role ID, group ID, the email address of the person you'd like to invite. You can optionally add a message that will be included in the invite email as well.

curl --request POST \
     --url '<<url>>:443/api/invites' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header 'Api-Branding: <<apiBranding>>' \
     --header "Authorization: Bearer $bearer_token" \
     --data '[
       {
         "groupRoles": [
           {
             "group": {
               "publicId": "$group_id"
             },
             "role": {
               "publicId": "$role_id"
             }
           }
         ],
         "emailAddress": "$email_address",
         "message": "$message"
       }
     ]'

A successful response to the request will look like the example below. 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 link if he or she currently doesn't have an IXON Cloud account.

{
  "status": "success",
  "type": "InviteResponse",
  "data": {
    "invites": [
      {
        "publicId": "$invite_id"
      }
    ],
    "userMemberships": [
      {
        "publicId": "$member_id"
      }
    ]
  }
}

Get a list of users

You can also keep a list of the users in your company in your own administration. To obtain that list you have to send a GET request to the UserList endpoint. You can find an example of this request below.

curl --request GET \
     --url '<<url>>:443/api/users' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

Remove a user

The UserList endpoint can be used to remove a user as well. You first have to obtain the User ID with the GET request in the example above. You then have to add that User ID to the DELETE request. An example of that request is given below.

curl --request DELETE \
     --url '<<url>>:443/api/users' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token" \
     --data '[{"$public_id": "$user_id"}]'

Manage users

👍
Field selection

Before you start: how to visualize groups

📘
Required module

Hierarchical tree

👍
Subgroups of a subgroup

Standard group view

User access structure explained

Terminology

Diagram explanation

Group management

🚧
Important notes

GroupList

GroupTypeList

GroupRoleList

👍
Note about permissions

Role, access categories and permissions management

RoleList

AudienceList

AudienceAgentReferenceList

AudienceAssetReferenceList

User management

Invite a user

Get a list of users

Remove a user

👍Field selection

Before you start: how to visualize groups

📘Required module

Hierarchical tree

👍Subgroups of a subgroup

Standard group view

User access structure explained

Terminology

Diagram explanation

Group management

🚧Important notes

GroupList

GroupTypeList

GroupRoleList

👍Note about permissions

Role, access categories and permissions management

RoleList

AudienceList

AudienceAgentReferenceList

AudienceAssetReferenceList

User management

Invite a user

Get a list of users

Remove a user

👍
Field selection

📘
Required module

👍
Subgroups of a subgroup

🚧
Important notes

👍
Note about permissions