User roles

User roles allow you to give your employees, partners, and customers just the right amount of access with simple cascading permissions, so you can safely delegate control where it is convenient. There are two basic user roles: admin and end-user.

The following table shows user permissions:

Before users (both admins or end-users) log in to Xively and use APIs, they must first have their Identity registered. Read on to get to know how to create a user in the system.


Emails must be unique

Emails are used as a primary key for users in your system, so are enforced to be unique within an Account.


The admin exists for the administration of the Account, and has permission over all entities for their Account.

This role has full permissions via the management API (HTTP) and messaging API (MQTT). Admin has full access to every device, user, group, as well as the capability to generate new App Credentials for the Account.

There can be more than one admin per an account. All the admins within one account have exactly the same access rights. They administer the account through the Xively management app. To add an admin, see Creating an admin.


End-users have limited access to entities, their permissions depend on the group they belong to. Since groups in Xively are hierarchical, you can build a system that does not require your users or business logic to manually confer permissions on new users as they sign up - they are already in their controlled environment, assigned to their group based on the user signup flow.

End-users have the following permissions on any group they are associated with, or any child groups of that group, and thus on other end-users and devices belonging to these groups:

An end-user has permissions to...

Create (POST)

Get one (GET/{id}) and List all (GET)

Update (PUT/{id})

Delete (DELETE/{id})

Devices within the group the end-user belongs to or within subgroups





End-users within the group the end-user belongs to or within subgroups





The group the end-user belongs to

Not applicable








Yes, but only when this group is empty (has no users and no devices)

An end-user account can be created with APIs or in the Xively management app. See respectively: Create an end-user with API or Creating an end-user in the Xively management app.


As an example of how a group hierarchy works, let’s see the following case: imagine a company that produces and services industrial air purifies. The company name is AirCo and it uses Xively to monitor all the devices that are in customer hands. AirCo has customers in three cities (Arlington, Brighton, and Cambridge), and in each city there are three buildings where the devices are in use.

Such hierarchy modelled in Xively consists of the top node (AirCo), its three children (three cities), and nine buildings (three in each city). Each node is a separate group, while each level is a separate group template.

Group templates define groups of the same kind: a city template defines all three cities groups, and a building template defines all groups for buildings.

Group hierarchy

Users who belong to AirCo group have access to all the users and devices in the hierarchy. Users who belong to Brighton group, have access to all the devices and users in Brighton and in its subgroups. Users who belong to Building A in Arlington group, have access to devices only in this building.

Such hierarchy can be expanded by further divisions, for example by adding floor numbers to each building if needed. The maximum number of levels is five, with unlimited number of children for a parent.

Groups or organizations?

Groups and group templates from the Xively management app are called "organizations" and "organizationTemplates" in the Blueprint model with the respective API endpoints: and

Groups and organizations are the same thing, the difference is only in the naming convention between Blueprint model and the Xively management app user interface.

Updated 3 years ago

User roles

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.