Overview
The auditing interface consists of three parts:
- The audit API resource returns URIs and URI templates to collections of audit records, so that they can be queried by criteria such as “all records from a particular user”, or “all records from a particular application”.
- The audit record collection resource retrieves audit records and enables creating new audit records.
- The audit record resource represents audit records that are individually queried.
Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.
Audited information
- Alarm modifications
- Operation modifications
- Two-factor authentication login attempts
- Smart rule modifications
- Complex Event Processing (CEP) module modifications
- User and group permissions modifications
- SSO and OAuth Internal logout and login attempts
Audit API
AuditRecords [application/vnd.com.nsn.cumulocity.auditApi+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URL linking to this resource. |
auditRecords | AuditRecordCollection | 1 | Collection of all audit records. |
auditRecordsForType | AuditRecordCollection URI template | 1 | Read-only collection of all audit records of a particular type (placeholder {type}). |
auditRecordsForUser | AuditRecordCollection URI template | 1 | Read-only collection of all audit records for a particular user (placeholder {user}). |
auditRecordsForApplication | AuditRecordCollection URI template | 1 | Read-only collection of all audit records for a particular application (placeholder {application}). |
auditRecordsForUserAndType | AuditRecordCollection URI template | 1 | Read-only collection of all audit records of a particular user and type (placeholder {user} and {type}). |
auditRecords ForUserAndApplication | AuditRecordCollection URI template | 1 | Read-only collection of all audit records for a particular user and application (placeholder {user} and {application}). |
auditRecords ForTypeAndApplication | AuditRecordCollection URI template | 1 | Read-only collection of all audit records of a particular type and application (placeholder {type} and {application}). |
auditRecords ForTypeAndUserAndApplication | AuditRecordCollection URI template | 1 | Read-only collection of all audit records of a particular type, user and application (placeholder {type}, {user} and {application}). |
GET the AuditAPI resource
Response body: application/vnd.com.nsn.cumulocity.auditApi+json
Required role: ROLE_AUDIT_READ
Example request: Retrieve AuditAPI resource
GET /audit
Host: ...
Authorization: Basic ...
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditapi+json;ver=...
Content-Length: ...
{
"self" : "<<AuditAPI URL>>",
"auditRecords" : { "self" :"<<AuditCollection URL>>" },
"auditRecordsForType" : "<<AuditCollection URL>>?type={type}",
"auditRecordsForUser" : "<<AuditCollection URL>>?user={user}",
"auditRecordsForApplication" : "<<AuditCollection URL>>?application={application}",
"auditRecordsForUserAndType" : "<<AuditCollection URL>>?user={user}&type={type}",
"auditRecordsForUserAndApplication" : "<<AuditCollection URL>>?user={user}&application={application}",
"auditRecordsForTypeAndApplication" : "<<AuditCollection URL>>?type={type}&application={application}",
"auditRecordsForTypeAndUserAndApplication" : "<<AuditCollection URL>>?type={type}&user={user}&application={application}"
}
Audit record collection
AuditRecordCollection [application/vnd.com.nsn.cumulocity.auditRecordCollection+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
auditRecords | array | 0..n | List of audit records, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of audit records. |
next | string | 0..1 | A URI linking to a potential next page of audit records. |
The “source” object of an audit record contains the properties “id” and “self”.
POST - create a new audit record
Request body: AuditRecord
Response body: AuditRecord
Required role: ROLE_AUDIT_ADMIN
Example request:
POST /audit/auditRecords
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.auditrecord+json;ver=...
{
"type" : "com_cumulocity_audit_LoginFailure",
"time" : "2011-09-06T12:03:27.845Z",
"text" : "Login failed after 3 attempts.",
"user" : "Spock",
"application" : "Omniscape",
"activity" : "login",
"severity" : "warning"
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.auditrecord+json;ver=...
Content-Length: ...
Location: <<URL of new audit record>>
{
"id" : "123",
"self" : "<<URL of new audit record>>",
"creationTime" : "2011-09-06T12:03:27.927Z",
"type" : "com_cumulocity_audit_LoginFailure",
"time" : "2011-09-06T12:03:27.845Z",
"text" : "Login failed after 3 attempts.",
"user" : "Spock",
"application" : "Omniscape",
"activity" : "login",
"severity" : "warning"
}
The “id” and “creationTime” of the new audit record are generated by the server and returned in the response to the POST operation.
GET audit records
Response body: AuditRecordCollection
Required role: ROLE_AUDIT_READ
Example request: Retrieve audit records
GET /audit/auditRecords
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.auditrecordcollection+json;
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditrecordcollection+json;ver=...
Content-Length: ...
{
"self" : "",
"auditRecords" : [
{
"id" : "123",
"self" : "<<AuditRecord 123 URL>>",
"creationTime" : "2011-09-06T12:03:27.927Z",
"type" : "com_cumulocity_audit_LoginFailure",
"time" : "2011-09-06T12:03:27.845Z",
"text" : "Login failed after 3 attempts.",
"user" : "Spock",
"application" : "Omniscape",
"activity" : "login",
"severity" : "warning"
}
],
"statistics" : {
"totalPages" : 3,
"pageSize" : 5,
"currentPage" : 1
}
}
In case of executing range queries on audit logs API, like query by dateFrom and dateTo, audits are returned by default in order from the newest to the oldest.
It is possible to change the order by adding query parameter “revert=false” to the request URL. An example request would be: “«url»/audit/auditRecords?dateFrom=2019-09-01&dateTo=2019-09-06T08:26:42%2B02:00&revert=false”.
Audit record
AuditRecord [application/vnd.com.nsn.cumulocity.auditRecord+json]
Name | Type | Occurs | Description | Mandatory for PUT/POST |
---|---|---|---|---|
id | string | 1 | Uniquely identifies this audit record. | No |
self | string | 1 | A URI linking to this resource. | No |
creationTime | datetime | 1 | Time when audit record was created in the database. | No |
type | string | 1 | Identifies the type of this audit record. | POST: Yes PUT: No |
time | datetime | 1 | Time of the audit record. | POST: Yes PUT: No |
text | String | 1 | Text description of the audit record. | POST: Yes PUT: No |
source | ManagedObject | 1 | An optional ManagedObject that the audit record originated from, as object containing properties “id” and “self”. | No |
user | string | 1 | The user responsible for the audited action. | No |
application | string | 1 | The application used to carry out the audited action. | No |
activity | string | 1 | The activity that was carried out. | POST: Yes PUT: No |
severity | string | 1 | The severity of action: critical, major, minor, warning or information. | No |
changes | array | 0..1 | An optional collection of objects describing the changes that were carried out. | No |
* | Object | 0..n | Additional properties of the audit record. | No |
Info:
source
can contain a ManagedObject withid
andself
properties. Also, in case of “Operation” type, it can contain an operationid
. In case of “Alarm” type, an alarmid
. In both cases, theself
link insource
is not correct, but it is kept there to not break the clients that expect to get a ManagedObject insource
.
GET an audit record
Response body: AuditRecord
Required role: ROLE_AUDIT_READ
Example request: Get a specific audit record
GET /audit/auditRecords/<<recordId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.auditrecord+json;
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditrecord+json;ver=...
Content-Length: ...
{
"id" : "123",
"self" : "<<AuditRecord URL>>",
"creationTime" : "2011-09-06T12:03:27.927Z",
"type" : "com_cumulocity_audit_LoginFailure",
"time" : "2011-09-06T12:03:27.845Z",
"text" : "Login failed after 3 attempts.",
"user" : "Spock",
"application" : "Omniscape",
"activity" : "login",
"severity" : "warning"
}