Overview
The user interface consists of the following parts:
- user API resource - returns URIs and URI templates to collections of users, groups, and roles, so that all users, groups, roles and user or group with particular name can be queried.
- user collection resource - retrieves sets of users and enables creating new users.
- user resource - represents individual users that can be queried and deleted.
- user reference collection resource - retrieves sets of references to users. These could be, for example, users with a particular global role. It also enables adding new users to a collection.
- user reference resource - represents one individual reference to a user, which can be retrieved or deleted.
- current user resource - represents the user that is logged in and can be queried and modified.
- group collection resource -retrieves sets of groups and enables creating new groups.
- group resource - represents individual groups that can be queried and deleted.
- group reference collection resource - retrieves sets of references to groups. Could be, for example, groups of a particular user.
- group reference resource - represents one individual reference to a group, which can be retrieved or deleted.
- role collection resource - retrieves sets of roles.
- role resource - represents individual roles that can be queried and assigned or unassigned to users or groups.
- role reference collection resource - retrieves sets of references to roles. Could be, for example, roles of a particular user or group.
- role reference resource - represents one individual reference to a role, which can be retrieved.
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:
- username - prefix or full username
- groups - numeric group identifiers separated by commas; result will contain only users which belong to at least one of specified groups
- owner - exact username
- onlyDevices - boolean flag. If set to “true”, result will contain only users created during bootstrap process (starting with “device_"). If flag is absent (or false) the result will not contain “device_” users.
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 |
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 |
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:
- API is one of the following values: “OPERATION”, “ALARM”, “AUDIT”, “EVENT”, “MANAGED_OBJECT”, “MEASUREMENT” or “*”
- fragment name is any fragment name, e.g. “c8y_Restart” or “*”
- permission is “ADMIN”, “READ” or “*”
Required permission per HTTP-method
- POST - “ADMIN” or “*”
- PUT - “ADMIN” or “*”
- DELETE - “ADMIN” or “*”
- GET - “READ” or “*”
“*” 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