Authentication and Authorization
See article Informations on authentication.
Request logs
Request:
- Endpoint: cloud-service-logging/accounts/$account/logs/paginated
- Method: GET
- URL Params:
- lang EN/DE
- limit 1..200
- categories OTHER, DEVICE
- marker string
Response:
{
"logs": [{
"id": uuid,
"messageId": string, // format 5 digit
"created": timestamp, // yyyy-mm-ddThh:mm:ss.SSSZ
"properties":{
"auditEntityId": uuid,
"auditNewValue": string,
"auditOldValue": string,
"auditSourceIp": string, // IPv4 address
"auditEntityName": string,
"auditEntityType": string,
"auditSourceAgent": string,
"auditOldValueChange": string,
"auditNewValueChange": string
},
"references":[
{
"id": uuid,
"type": string // account, addin, device, network, principal, site, page
},
{
"id": uuid,
"type": string,
"name": string
}],
"data":[],
"accountId": uuid,
"originatorId": uuid,
"serviceId": uuid,
"serviceName": string,
"logLevel": string, // INFO, WARNING, ERROR
"message": string
"isAuditLog": boolean
},
...
],
"next": string, // this parameter is optional
"previous": string // this parameter is optional
}
Markers
The log messages API returns up to two markers: next and previous. These markers have the following format:
{
"type": string // NEXT_PAGE, PREVIOUS_PAGE
"logCreatedAt": timestamp // seconds from 1/1/1970
"logPersistedAt": timestamp // seconds from 1/1/1970
}
The marker is the url-encoded version of next field.
It is possible to request the logs newer than a specific timestamp:
curl -X GET -H "accept: application/json" -H "Authorization: Bearer $token" https://cloud.lancom.de/cloud-service-logging/accounts/$account/logs/paginated?lang=EN&categories=OTHER&marker=%7B%22type%22:%22PREVIOUS_PAGE%22,%22logCreatedAt%22:1613145056300000%7D
Reference Resolution
The log object contains different types of references, the reference format is:
{
"id": uuid
"type": string
"name": string
}
The id and type are mandatory and always present in the reference object. The name is optional, and present only for the reference of type principal.
Account
This reference represents the project, the organization or the distribution.
Request:
- Endpoint: /cloud-service-auth/accounts
- Method: GET
- URL params:
- id: list of account uuids
Response:
[
{
"name": string,
"id": uuid,
"parent": uuid,
...
"identifier": string,
"created": timestamp, // yyyy-mm-ddThh:mm:ss.SSS+ZZ:ZZ
...
}
]
Addin
Request:
- Endpoint: /cloud-service-config/configapplication/accounts/$account/applications
- Method: GET
Response:
[
{
"name": string,
"enabled": boolean,
"type": string,
...
"id": uuid
},
...
]
Device
Request:
- Endpoint: cloud-service-devices/accounts/$account/devices
- Method: GET
- URL params:
- id: device uuid
Response:
[
{
"id": uuid,
"status": {
"name": string,
"serial": string,
...
},
...
}
]
Network
Request:
- Endpoint: /confignetwork/accounts/$account/networks
- Method: GET
Response:
[
{
"id": uuid,
"name": string,
...
]
Principal
Request:
- Endpoint: /cloud-service-auth/accounts/$account/members
- Method: GET
- URL params:
- id: principal uuid
Response:
[
{
"id": uuid,
"icon": string,
"name": string,
"email": string,
...
}
]
Site
Request:
- Endpoint: /cloud-service-devices/accounts/$account/sites
- Method: GET
- URL params:
- id: site uuid
Response:
[
{
"name": string,
"comment": string,
...
"id": uuid,
...
}
]
Page
The page reference has a static resolution:
| UUID | EN | DE |
|---|---|---|
| 03acf5fd-aa64-4cfe-8a67-4a0f7d4a59a3 | "Notification Settings" | "Benachrichtigungseinstellungen" |
| b3feccdc-cd04-4e45-82f6-b4603737dda8 | "Log Download" | "Log-Download" |
Template and Reference
The log messages are immutable, it is not possible to change in the database. The rendering of the messages changes, we use a template to then be able to have the updated naming of devices, networks, principals...
Here some template examples:
"User {ref:f16783c3-cb0c-3727-95c1-0752f938f7a7} has logged in for this account"
"The device {ref:ce4e47f6-c374-44dd-ba58-750a06e9c363} has established its cloud connectivity."
The string {ref:uuid} is replaced with name of the reference. Some references have the name embedded in the log messages (e.g. metric, principal), other references only specify the type and the uuid. The name resolution then requires an additional call to the corresponding API, listed above.
It is recommended to cache the reference resolution in order to reduce the amount of API call.
