Users

Overview

The user interface consists of the following parts:

Info: “Realm” as used in this API usually corresponds to a tenant.

For all PUT/POST requests an accept header should be provided, otherwise an empty response body will be returned.

User API

UserAPI [application/vnd.com.nsn.cumulocity.userApi+json]

Name Type Occurs Description
self string 1 A URL linking to this resource.
userByName URI Template/User 1 Reference to a resource of type User. The template contains placeholders {realm} and {userName}.
users URI Template/UserCollection 1 Collection of all users belonging to a given realm. The template contains a placeholder {realm}.
currentUser URI Template/User 1 Reference to the resource of the logged in user.
groupByName URI Template/Group 1 Reference to a resource of type Group. The template contains placeholders {realm} and {groupName}.
groups URI Template/GroupCollection 1 Collection of all users belonging to a given realm. The template contains a placeholder {realm}.
roles URI Template/RoleCollection 1 Collection of all roles.

GET the user API resource

Response body: userApi

Example request: Retrieve information about user API resource

GET /user
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.nsn.cumulocity.userapi+json;ver=0.9

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.userapi+json;ver=0.9
Content-Length: nnn
{
     "self" : "<<UserAPI URL>>",
     "userByName" : "<<URL to the UserByName resource with realm and user name parameter>>",
     "users" : "<<URL to the UserCollection resource with realm parameter>>",
     "currentUser" : "<<URL to the CurrentUser resource>>",
     "groupByName" : "<<URL to the GroupByName resource with realm and group name parameter>>",
     "groups" : "<<URL to the GroupCollection resource with realm parameter>>",
     "roles" : "<<URL to the RoleCollection resource>>"
}

User collection

UserCollection [application/vnd.com.nsn.cumulocity.userCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
users array 0..n List of users.
statistics PagingStatistics 1 Information about the paging statistics.
prev string 0..1 A URI linking to a possible previous page with additional users.
next string 0..1 A URI linking to a possible next page with additional users.

GET a representation of a user collection

Response body: userCollection

Example request: Retrieve information about a user collection

GET /user/<<tenant>>/users
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.nsn.cumulocity.usercollection+json;ver=0.9

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.usercollection+json;ver=0.9
Content-Length: nnn
{
   "self":"[URL to this resource]",
   "users":[
        {
          "id" : "jsmith",
          "self" : "[URL to the resource]",
          "userName" : "jsmith",
          "firstName" : "John",
          "lastName" : "Smith",
          "phone" : "+1234567890",
          "email" : "jsmith@abc.com",
          "enabled" : true,
          "groups" : {[collection of groups the user belongs to]},
          "roles" : {[collection of roles the user has]},
          "devicePermissions": {}
        }, ... {
          "id" : "mblack",
          "self" : "[URL to the resource]",
          "userName" : "mblack",
          "firstName" : "Michael",
          "lastName" : "Black",
          "phone" : "+10988765432",
          "email" : "mblack@abc.com",
          "enabled" : true,
          "groups" : {[collection of groups the user belongs to]},
          "roles" : {[collection of roles the user has]},
          "devicePermissions": {}
        }
   ],
   "statistics" : {
       "totalPages" : 22,
       "pageSize" : 5,
       "currentPage : 1
   },
   "prev" : "[URL to previous page]",
   "next" : "[URL to next page]"
}

Users in the response are sorted by username in ascending order.

Search parameters for User Collection

Users can be filtered by following parameters:

Additional flag “withSubusersCount” - if set to “true”, then each of returned users will contain additional field “subusersCount” - number of direct subusers (users with corresponding “owner”).

Example request: retrieve users, where username starts with “js”, and every user belongs to one of the groups 2, 3 or 4, and the owner is “admin”, and is not a device user.

GET /user/<<tenant>>/users?username=js&groups=2,3,4&owner=admin&withSubusersCount=true
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.nsn.cumulocity.usercollection+json;ver=0.9

POST - create a new user within the collection

Request body: User

Response body: User 

Example request: Create a new user

POST /user/<<tenant>>/users
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
{
  "userName" : "jsmith",
  "password" : "password",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "customProperties" : {"language":"en"},
  "email" : "jsmith@abc.com",
  "enabled" : true,
  "sendPasswordResetEmail": true
}

Example response:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn
 Location: [location]
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "email" : "jsmith@abc.com",
  "customProperties" : {"language":"en"},
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

User

User [application/vnd.com.nsn.cumulocity.user+json]

A “User” resource type contains the following fields:

Name Type Occurs Description Allowed in PUT/POST request
id string 1 Uniquely identifies a user. not allowed
self string 1 A URI linking to this resource. not allowed
userName string 1 User name, unique for a given domain. Max: 1000 characters. Whitespaces, slashes, +$: characters not allowed. POST: mandatory PUT: not allowed
password string 1 User password. Min: 6, max: 32 characters. Only Latin1 chars allowed. If you do not specify a password when creating a new user with a POST request, it must contain the field sendPasswordResetEmail with a value of true. optional
sendPasswordResetEmail boolean 1 When set to true, this field will cause Cumulocity IoT to send a password reset email to the email address specified. If there is no password specified when creating a new user with a POST request, this must be specified and it must be set to true. optional
firstName string 1 User first name. optional
lastName string 1 User last name. optional
phone string 1 User phone number. Format: “+[country code][number]", has to be a valid MSISDN optional
email string 1 User email address. optional
enabled boolean 1 User activation status (true/false). optional
customProperties Object 1 Keeps a list of custom properties. optional
groups array 1 List of group references. not allowed
roles array 1 List of role references. not allowed
devicePermissions object 1 List of device permissions. optional

Embedded user contains all properties except password. Password property is never returned in GET user.

User [application/vnd.com.nsn.cumulocity.currentUser+json]

A “currentUser” resource type contains the following fields:

Name Type Occurs Description Allowed in PUT/POST request
id string 1 Uniquely identifies a user. not allowed
self string 1 A URI linking to this resource. not allowed
userName string 1 User name, unique for a given domain. Max: 1000 characters POST: mandatory PUT: not allowed
password string 1 User password. Min: 6, max: 32 characters. Only Latin1 chars allowed. optional
firstName string 1 User first name. optional
lastName string 1 User last name. optional
phone string 1 User phone number. Format: “+[country code][number]", has to be a valid MSISDN optional
email string 1 User email address. optional
enabled boolean 1 User activation status (true/false). optional
devicePermissions object 1 List of device permissions. optional
effectiveRoles array 0..n List of all roles assigned to a current user (explicitly or implicitly via associated groups). not allowed

userName can have a maximum of 1000 characters.

Embedded user contains all properties except password. Password property is never returned in GET user.

Device permission structure

[API:fragment_name:permission] where:

Required permission per HTTP-method

“*” is a wildcard. It enables you to access every API and CRUD object regardless of fragments that are inside it.

Querying collections

Only objects which the user is allowed to see are returned to the user. It is possible to query next page using next link from page statistics. It is important to note that in this case the “currentPage” field represents the offset instead of the actual page number.

Important: If there is no fragment in an object, then for example to read the object, you have to use the wildcard “*” for the “fragment_name” part of the device permission (see the structure above). For example: "10200":["MEASUREMENT:*:READ"].

Audit log

Any change in user’s roles, device permissions and groups creates corresponding audit records with type ‘User’ and activity ‘User updated’ with information which properties have been changed.

GET a representation of a user

Response body: User

Example request: Retrieve information about a user

GET /user/<<tenant>>/users/<<userId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
Content-Length: nnn
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "email" : "jsmith@abc.com",
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

The user password is never returned in a GET response. Authentication mechanism is provided by another interface.

GET a representation of a user by his/her name

Response body: User

Example request: Retrieve information about a user

GET /user/<<tenant>>/userByName/<<userName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
Content-Location: [location]
Content-Length: nnn
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "email" : "jsmith@abc.com",
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

PUT a change to user resource

Request body: User

Response body: User 

Example request: Change the first name of a user

PUT /user/<<tenant>>/users/<<userId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn
{
   "firstName" : "Robert"
}

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
Content-Length: nnn
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "Robert",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  {emailcloak=off}"email" : "jsmith@abc.com",
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

When the user is updated with changed permissions or groups, a corresponding audit record is created with type ‘User’ and activity ‘User updated’.

DELETE a representation of a user

Request body: n/a

Response body: n/a

Example request: Delete a user

DELETE /user/<<tenant>>/users/<<userName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT

GET the current user resource

Response body: user

or

Response body: currentUser

Example request: Retrieve information about the logged-in user

GET /user/currentUser
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9

Example response:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn

{
    "email": "jsmith@abc.com",
    "enabled": true,
    "firstName": "John",
    "devicePermissions": {},
    "groups": {
        "references": [...],
        "self": "[URL to User's Groups]"
    },
    "id": "jsmith",
    "lastName": "Smith",
    "phone": "+1234567890",
    "roles": {
        "references": [...],
        "self": "[URL to the User's Roles]"
    },
    "self": "[URL to the User resource]",
    "userName": "jsmith"}

PUT a change to the current user resource

Request body: user

Response body: user

Example request: Change the first name of the logged-in user

PUT /user/currentUser
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn

{
   "firstName" : "Robert"
}

Example response:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn

 {
    "email": "jsmith@abc.com",
    "enabled": true,
    "firstName": "Robert",
    "groups": {
        "references": [...],
        "self": "[URL to User's Groups]"
    },
    "id": "jsmith",
    "lastName": "Smith",
    "phone": "+1234567890",
    "roles": {
        "references": [...],
        "self": "[URL to the User's Roles]"
    },
    "self": "[URL to the User resource]",
    "userName": "jsmith",
    "devicePermissions": {}
 }

User reference collection

UserReferenceCollection [application/vnd.com.nsn.cumulocity.userReferenceCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
references array 0..n List of user references.
statistics object 1 Information about the paging statistics.
prev string 0..1 A URI linking to a possible previous page with additional user references.
next string 0..1 A URI linking to a possible next page with additional user references.

Add user to a group

Request body: UserReference

Response body: UserReference

Example request: Create a new UserReference

POST /user/<<tenant>>/groups/<<groupId>>/users
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.userreference+json;ver=0.9

{
  "user" : {
    "self" : "[URL to the User resource]"
  }
}

Example response:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.userreference+json;ver=0.9
 Content-Length: nnn
 Location: [location]

{
    "self": "[URL to this resource]",
    "user": {
        "email": "jsmith@abc.com",
        "enabled": true,
        "firstName": "John",
        "groups": {
            "references": [...],
            "self": "[URL to the User's Groups]"
        },
        "id": "jsmith",
        "lastName": "Smith",
        "phone": "+1234567890",
        "roles": {
            "references": [...],
            "self": "[URL to the User's Roles]"
        },
        "self": "[URL to the User resource]",
        "userName": "jsmith"
    }}

When a user is added to a group, a corresponding audit record is created with type ‘User’ and activity ‘User updated’.

Remove user from a group

Request body: n/a

Response body: n/a

Example request: Delete a UserReference

 DELETE /user/<<tenant>>/groups/<<groupId>>/users/<<yourUserName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT

When a user is removed from a group, a corresponding audit record is created with type ‘User’ and activity ‘User updated’.

Get all users of a group

Response body: UserReferenceCollection

Example request: Retrieve information about all users of a group

GET /user/management/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.userreferencecollection+json;ver=0.9

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.userreferencecollection+json;ver=0.9
Content-Length: nnn

{
  "self" : "[URL to this resource]",
  "references" : [
    {
      "self" : "[URL to this UserReference resource]",
      "user" : {
        "self" : "[URL to this User resource]",
        "id" : "1",
        "userName" : "jsmith",
        ...
      }
    }
  ],
  "statistics" : {
    "totalPages" : 3,
    "pageSize" : 5,
    "currentPage : 1
  },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

User reference

UserReference [application/vnd.com.nsn.cumulocity.userReference+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
user User 1 User resource being referenced.

Group collection

GroupCollection [application/vnd.com.nsn.cumulocity.groupCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
groups Group 0..n List of groups
statistics PagingStatistics 1 Information about the paging statistics.
prev string 0..1 A URI linking to a possible previous page with additional groups.
next string 0..1 A URI linking to a possible next page with additional groups.

Audit log

Any change in group’s roles and device permissions creates corresponding audit records with type ‘Group’ and activity ‘Group updated’ with information which properties have been changed.

List all groups

Response body: GroupCollection

Example request: Retrieve information about a group collection

GET /user/management/groups/
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.groupcollection+json;ver=0.9

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.groupcollection+json;ver=0.9
Content-Length: nnn

{
   "self":"[URL to this resource]",
   "groups": [
        {
          "id" : "1",
          "self" : "[URL to this resource]",
          "name" : "administrators",
          "roles" : [...],
          "users" : ["self" : "[URL to collection of Users in this Group]"],
          "devicePermissions": {}
        },
        {
          "id" : "2",
          "self" : "[URL to this resource]",
          "name" : "readers",
      "roles" : [...],
          "users" : ["self" : "[URL to collection of Users in this Group]"],
          "devicePermissions": {}
        }
   ],
   "statistics" : {
       "totalPages" : 2,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

Create a group

Request body: Group

Response body: Group

Example request: Create a new group

POST /user/management/groups
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9

{
  "name" : "monitoring"
}

Example response:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
 Content-Length: nnn
 Location: [URL to the resource]

{
  "id" : "3",
  "self" : "[URL to this resource]",
  "name" : "monitoring"
  "users" : {
    "self" : "[URL to the UserReferenceCollection resource]",
    "references" : []
  },
  "roles" : {
    "self" : "[URL to the RoleReferenceCollection resource]",
    "references" : []
  },
  "devicePermissions": {}
}

Group

Group [application/vnd.com.nsn.cumulocity.group+json]

Name Type Occurs Description Allowed in PUT/POST request
id string 1 Uniquely identifies a group. not allowed
self string 1 A URI linking to this resource. not allowed
name string 1 Descriptive name of the group. mandatory
roles array 1 List of role references. not allowed
devicePermissions object 1 List of device permissions. optional

Show group details

Response body: Group

Example request: Retrieve information about a group

GET /user/management/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.group+json;ver=0.9

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
Content-Length: nnn

{
  "id" : "1",
  "self" : "[URL to this resource]",
  "name" : "administrators",
  "devicePermissions": {},
  "roles" : {
    "self" : "[URL to the RoleReferenceCollection resource]",
    "references" : [
    {
      "self" :  "[URL to the RoleReference resource]",
      "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "1",
          "name" : "ROLE_USER_MANAGEMENT_ADMIN"
      }
    },
    {
      "self" :  "[URL to the RoleReference resource]",
      "role" : {
            "self" :  "[URL to the Role resource]",
            "id" : "1",
            "name" : "ROLE_INVENTORY_MANAGEMENT_ADMIN"
          }
        },
    ...
     ]
}

GET a representation of a group by its name

Response body: Group

Example request: Retrieve information about a group

GET /user/<<tenant>>/groupByName/<<groupName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.group+json;ver=0.9

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
Content-Location: [main URL of this resource]
Content-Length: nnn

{
  "id" : "1",
  "self" : "[URL to this resource]",
  "name" : "administrators",
  ...
}

Remove a group

Request body: n/a

Response body: n/a

Example request: Delete a group

DELETE /user/<<tenant>>/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT

When a group is removed, a corresponding audit record is created with type ‘User’ and activity ‘User updated’ with the information that the user has been removed from the group.

Info: ADMINS and DEVICES groups can not be deleted.

Update a group

Request body: Group

Response body: Group

Example request: Change the group name

PUT /user/<<tenant>>/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
 Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
 Content-Length: nnn

{
   "name" : "PlatformAdministrators"
}

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
Content-Length: nnn

{
  "id" : "1",
  "self" : "[URL to this resource]",
  "name" : "PlatformAdministrators",
  ...
}

When a group is updated with changed roles or permissions, a corresponding audit record is created with type ‘Group’ and activity ‘Group updated’.

Group reference collection

GroupReferenceCollection [application/vnd.com.nsn.cumulocity.groupReferenceCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
groups array 0..n List of group references.
statistics PagingStatistics 1 Information about the paging statistics.
prev string 0..1 A URI linking to a possible previous page with additional group references.
next string 0..1 A URI linking to a possible next page with additional group references.

Get all groups of a user

Response body: GroupReferenceCollection

Example request: Retrieve information about all groups of a user

GET /user/<<tenant>>/users/<<userName>>/groups
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.groupreferencecollection+json;ver=0.9

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.groupreferencecollection+json;ver=0.9
Content-Length: nnn

{
    "self" : "[URL to this resource]",
    "references": [{        "group": {            "id": 21,            "name": "admins",            "roles": {                "references": [...],                "self": "[URL to this Group's Roles]"            },            "self": "[URL to this Group]",            "users": {                "self": "{URL to this Group's Users]"            }        },        "self": "[URL to this User's Group]"    },   ...   ],   "statistics" : {
     "totalPages" : 1,
     "pageSize" : 5,
     "currentPage : 1
   },
   "prev" : "[URL to previous page]",
   "next" : "[URL to next page]"
}

Group reference

GroupReference [application/vnd.com.nsn.cumulocity.groupReference+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
group Group 1 Group resource being referenced.

Role collection

RoleCollection [application/vnd.com.nsn.cumulocity.roleCollection+json]

Field Name Type Occurs Description
self string 1 A URI linking to this resource.
roles array 0..n List of roles.
statistics PagingStatistics 1 Information about the paging statistics.
prev string 0..1 Link to a possible previous page with additional roles.
next string 0..1 Link to a possible next page with additional roles.

Role

Role [application/vnd.com.nsn.cumulocity.role+json]

Name Type Occurs Description
id string 1 Uniquely identifies a role.
name string 1 Descriptive name of the role, following role naming pattern.

Get all available roles

Response body: RoleCollection

Example request: Retrieve information about a role collection

 GET /user/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.rolecollection+json;ver=0.9
 Content-Length: nnn

{
   "self":"[URL to this resource]",
   "roles": [
     {
       "self" :  "[URL to the Role resource]",
       "id" : "ROLE_INVENTORY_ADMIN",
       "name" : "ROLE_INVENTORY_ADMIN"
     },
     {
       "self" :  "[URL to the Role resource]",
       "id" : "ROLE_USER_MANAGEMENT_ADMIN",
       "name" : "ROLE_USER_MANAGEMENT_ADMIN"
     },    ...
   ],
   "statistics" : {
       "totalPages" : 5,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

Assign Role to user

Request body: RoleReference

Response body: RoleReference

Example request: Create a new RoleReference

POST /user/<<tenant>>/users/<<userName>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.rolereference+json;ver=0.9

{
  "role" : {
    "self" : "[URL to the Role resource]"
  }
}

Example response:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.rolereference+json;ver=0.9
 Content-Length: nnn
 Location: [URL to this resource]

{
  "self" : "[URL to this resource]",
  "role" : {
    "self" :  "[URL to the Role resource]",
    "id" : "ROLE_USER_MANAGEMENT_ADMIN",
    "name" : "ROLE_USER_MANAGEMENT_ADMIN"
  }
}

When a role is assigned to a user, a corresponding audit record is created with type ‘User’ and activity ‘User updated’.

Assign role to group

Request body: RoleReference

Response body: RoleReference

Example request: Create a new RoleReference

POST /user/<<tenant>>/groups/<<groupId>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.rolereference+json;ver=0.9

{
  "role" : {
    "self" : "[URL to the Role resource]"
  }
}

Example response:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.rolereference+json;ver=0.9
 Content-Length: nnn
 Location: [URL to this resource]

{
  "self" : "[URL to this resource]",
  "role" : {
    "self" :  "[URL to the Role resource]",
    "id" : "ROLE_USER_MANAGEMENT_ADMIN",
    "name" : "ROLE_USER_MANAGEMENT_ADMIN"
  }
}

When a role is assigned to a group, a corresponding audit record is created with type ‘Group’ and activity ‘Group updated’.

Unassign role from user

Request body: n/a

Response body: n/a

Example request: Delete a RoleReference

DELETE /user/<<tenant>>/users/<<userName>>/roles/<<roleName>> (Example:ROLE_TENANT_MANAGEMENT_ADMIN)}}
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT

Unassign role from group

Request body: n/a

Response body: n/a

Example request: Delete a RoleReference

DELETE /user/<<tenant>>/groups/<<groupId>>/roles/<<roleName>> (Example:ROLE_TENANT_MANAGEMENT_ADMIN)}}
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT

When a role is unassigned from a group, a corresponding audit record is created with type ‘Group’ and activity ‘Group updated’.

Role reference collection

RoleReferenceCollection [application/vnd.com.nsn.cumulocity.roleReferenceCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
references array 0..n List of role references.
statistics PagingStatistics 1 Information about the paging statistics.
prev string 0..1 A URI linking to a possible previous page with additional role references.
next string 0..1 A URI linking to a possible next page with additional role references.

Get all roles of a user

Response body: RoleReferenceCollection

Example request: Retrieve information about a role reference collection

GET /user/<<tenant>>/users/<<userName>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.rolereferencecollection+json;ver=0.9

Example response:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.rolereferencecollection+json;ver=0.9
 Content-Length: nnn
{
   "self":"[URL to this resource]",
   "references": [
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_INVENTORY_ADMIN",
          "name" : "ROLE_INVENTORY_ADMIN"
       }
     },
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_USER_MANAGEMENT_ADMIN",
          "name" : "ROLE_USER_MANAGEMENT_ADMIN"
       }
     }
   ],
   "statistics" : {
       "totalPages" : 1,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

Get all roles of a group

Response body: RoleReferenceCollection

Example request: Retrieve information about a role reference cCollection

GET /user/<<tenant>>/groups/<<groupId>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.rolereferencecollection+json;ver=0.9

Example response:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.rolereferencecollection+json;ver=0.9
 Content-Length: nnn

{
   "self":"[URL to this resource]",
   "references": [
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_INVENTORY_ADMIN",
          "name" : "ROLE_INVENTORY_ADMIN"
       }
     },
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_USER_MANAGEMENT_ADMIN",
          "name" : "ROLE_USER_MANAGEMENT_ADMIN"
       }
     }
   ],
   "statistics" : {
       "totalPages" : 1,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

Role reference

RoleReference [application/vnd.com.nsn.cumulocity.roleReference+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
role Role 1 A role resource being referenced.

Inventory role collection

InventoryRoleCollection [application/vnd.com.nsn.cumulocity.inventoryrolecollection+json]

Field Name Type Occurs Description
self string 1 A URI linking to this resource.
roles array 0..n List of roles.
statistics object 1 Information about the paging statistics.
prev string 0..1 A URI linking to a possible previous page with additional roles.
next string 0..1 A URI linking to a possible next page with additional roles.

Get all available inventory roles

Required role: ROLE_USER_MANAGEMENT_READ or ROLE_USER_MANAGEMENT_CREATE

Response body: InventoryRoleCollection

Example request:

GET /user/inventoryroles
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

{
    "self": "[URL to this resource]",
    "statistics": {
        "totalPages": 1,
        "currentPage": 1,
        "pageSize": 5
    },
    "roles": [
        {
            "name": "Manager",
            "description": "Can read all data of the asset and manage all inventory data, but cannot perform operations. Can also acknowledge and clear alarms. Can create and updates dashboards.",
            "self": "[URL to this resource]",
            "id": 2,
            "permissions": [
                {
                    "permission": "READ",
                    "id": 1,
                    "type": "*",
                    "scope": "*"
                },
                {
                    "permission": "ADMIN",
                    "id": 2,
                    "type": "*",
                    "scope": "MANAGED_OBJECT"
                },
                {
                    "permission": "ADMIN",
                    "id": 3,
                    "type": "*",
                    "scope": "ALARM"
                }
            ]
        },
        {
            "name": "Operations: Restart Device",
            "description": "Can restart devices.",
            "self": "[URL to this resource]",
            "id": 4,
            "permissions": [
                {
                    "permission": "READ",
                    "id": 5,
                    "type": "*",
                    "scope": "MANAGED_OBJECT"
                },
                {
                    "permission": "READ",
                    "id": 7,
                    "type": "c8y_Restart",
                    "scope": "OPERATION"
                },
                {
                    "permission": "ADMIN",
                    "id": 6,
                    "type": "c8y_Restart",
                    "scope": "OPERATION"
                }
            ]
        }
    ]
}

Assign a new inventory role

Required role: ROLE_USER_MANAGEMENT_ADMIN

Request body: InventoryRole

Response body: InventoryRole

Example request:

POST /user/inventoryroles
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.nsn.cumulocity.inventoryrole+json

{
    "name": "Reader",
    "description": "Can read all data of the asset.",
    "permissions": [
        {
            "permission": "READ",
            "type": "*",
            "scope": "*"
        }
    ]
}

Example response:

{
    "name": "Reader",
    "description": "Can read all data of the asset.",
    "self": "[URL to this resource]",
    "id": 10,
    "permissions": [
        {
            "permission": "READ",
            "id": 11,
            "type": "*",
            "scope": "*"
        }
    ]
}

Inventory role

InventoryRole [application/vnd.com.nsn.cumulocity.inventoryrole+json]

Name Type Occurs Description Mandatory for POST/PUT
id string 1 Uniquely identifies an inventory role. No/Yes
name string 1 Descriptive name of the inventory role. Yes/No
description string 1 Details of the capabilities of the role. No
self string 1 A URI linking to this resource. No
permissions array 0..n List of permissions that can be attached to group of devices. No

Retrieve an inventory role

Required role: ROLE_USER_MANAGEMENT_READ or ROLE_USER_MANAGEMENT_CREATE and the user has the inventory role assigned

Response body: InventoryRole

Example request:

GET /user/inventoryroles/{id}
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

{
    "name": "Reader",
    "description": "Can read all data of the asset.",
    "self": "[URL to this resource]",
    "id": 10,
    "permissions": [
        {
            "permission": "READ",
            "id": 11,
            "type": "*",
            "scope": "*"
        }
    ]
}

Update an inventory role

Required role: ROLE_USER_MANAGEMENT_ADMIN

Request body: InventoryRole

Response body: InventoryRole

Example request:

PUT /user/inventoryroles/{id}
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.nsn.cumulocity.inventoryrole+json

{
    "description": "Grants read access to the asset's data."
}

Example response:

{
    "name": "Reader",
    "description": "Grants read access to the asset's data.",
    "self": "[URL to this resource]",
    "id": 10,
    "permissions": [
        {
            "permission": "READ",
            "id": 11,
            "type": "*",
            "scope": "*"
        }
    ]
}

Delete an inventory role

Required role: ROLE_USER_MANAGEMENT_ADMIN

Example request:

DELETE /user/inventoryroles/{id}
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx