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 URL 1 Link 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 URI 1 Link to this resource
users User 0..n List of users
statistics PagingStatistics 1 Information about the paging statistics
prev URI 0..1 Link to a possible previous page with additional users
next URI 0..1 Link 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 URI 1 Link 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 POST: mandatory PUT: 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 GroupReferenceCollection 1 List of group references not allowed
roles RoleReferenceCollection 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 URI 1 Link 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 POST: mandatory PUT: 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 Role 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 an object does not have any fragment in it, then to for example read that object, you have to put a wildcard to the fragment name part of device permission, i.e. “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 URI 1 Link to this resource
references UserReference 0..n List of user references
statistics PagingStatistics 1 Information about the paging statistics
prev URI 0..1 Link to a possible previous page with additional user references
next URI 0..1 Link 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 URI 1 Link 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 URI 1 Link to this resource
groups Group 0..n List of groups
statistics PagingStatistics 1 Information about the paging statistics
prev URI 0..1 Link to a possible previous page with additional groups
next URI 0..1 Link 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 URI 1 Link to this resource not allowed
name String 1 Descriptive name of the group mandatory
roles RoleReferenceCollection 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 URI 1 Link to this resource
groups GroupReference 0..n List of group references
statistics PagingStatistics 1 Information about the paging statistics
prev URI 0..1 Link to a possible previous page with additional group references
next URI 0..1 Link 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 URI 1 Link 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 URI 1 Link to this resource
roles Role 0..n List of roles
statistics PagingStatistics 1 Information about the paging statistics
prev URI 0..1 Link to a possible previous page with additional roles
next URI 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 URI 1 Link to this resource
references RoleReference 0..n List of role references
statistics PagingStatistics 1 Information about the paging statistics
prev URI 0..1 Link to a possible previous page with additional role references
next URI 0..1 Link 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 URI 1 Link to this resource
role Role 1 A role resource being referenced