Audit Trail API v2 (REST API)

Prerequisite

The Audit Trail API catalog and addresses can only be accessed when:

you have subscribed the Audit Trail option with TrustBuilder
created a "Logs" enabled certificate API in the administration console

How to create the API certificate?

All calls to this API are performed on a per service base. Accessing the audit trail for a given service requires a valid certificate. You may generate this certificate in your administration console.

Connect to the administration console
Navigate to the appropriate service view
Go to "Secure Sites" and click on the "Download a new certificate for the API" button
Do not forget to set the certificate Right "Logs" option to "Yes"

Once you have downloaded your certificate, you may use it to make calls to the API.

You should add your certificate to your browser.

The method is different for each browser.

Overview

TrustBuilder MFA provides a Strong Authentication as a Service solution and an fully documented API to manage and browse the Audit trail.

Audit trail life-cycle mechanism

The Audit trail life-cycle is divided in 3 stages with distinctive time-frame, access time and storage mode.

A REST API available in a 3 stages life-cycle

Online

This stage is designed for browsing and troubleshooting recent accesses.
Mainly for Help-desk and Assistance operations
Duration : The last five weeks
Performance bases accesses for frequent exports
Direct access through the API

Glacier

This step is a service (commercial) option and only designed for compliance with specific trades with a legal records obligation
Duration : Years,
Long term archive stored by years

Point to be noted: standard offers are restricted to a 1 Year limit

Time distribution mechanism (Sharding)

Every Audit trail is sharded by time period
API clients *must* specify the requested shard ID(s)

Be mindful of gaps: past shards are always complete but last shards can lack most recent entries
Be mindful of order: trails could be « unsorted » (hence the possibility of gaps)

How to access the TrustBuilder MFA Audit Trail REST API catalog

As stated in the prerequisite, you can only access Audit Trails API address with the “inWebo” option and "logs" enabled certificate.
Please see “Accessing the Audit trail” documentation to get access to our Audit trail API and documentation.

Audit Trail API Interactive Interface and documentation

Here you can access directly the API and the Interactive Interface with its documentation.

Classical Interface: https://kiwi.myinwebo.com/audit/apidocs/public/
Interactive interface: https://kiwi.myinwebo.com/audit/apidocs/public/ui/index.html

Sample of Request URL

BASH

https://api.myinwebo.com/audit/v2/customer/logs/archive?limit=50&months=202003&page=0

Sample of CURL command line

BASH

curl -X GET --header 'Accept: application/json' 'https://api.myinwebo.com/audit/v2/customer/logs/archive?limit=50&months=202003&page=0'

How to find out the periods (months or weeks) that can be viewed in the audit trail

Each available API endpoint is associated with another endpoint allowing to retrieve the available months

example:
For the / audit / v2 / client / logs / archive endpoint, you can consult the following address: / audit / v2 / client / logs / archive / month
which will return the list of available months (in .json format) at the date of your request.

"202008", "202007", "202006", "202005", "202004", ....

So you don't need to calculate these values before launching your API query.

Paging and "hasMore" value

All the results of the audit trail logs are paginated, so to know when the results exceed the value of the "limit" defined in your REST request, you must check the value "hasMore" in the result .json.

If in the result .json the value "hasMore" returns "false" it means that there is no next page and it is not necessary to continue.
If in the result .json the value "hasMore" returns "true", this means that the result of this request continues on the next page, you will have to re-launch the same request but increasing the value "page" by 1.
Initial "page" value: 0
max "limit" value: 100

Available REST API endpoints in the TrustBuilder MFA Audit trail catalog

The Audit Trail allows you to access to the following categories:

V2 Audit Online Service

This service allows you to access data available in the last 5 weeks of activity / sharded per weeks.

V2 Audit Service

This category allows you to find and browse the activity in the Audit section on a monthly basis.
Starting with the 12th previous month i.e. the current month but from the previous year and ending with the last month (full 12 months available).

V2 Audit Glacier service

This service allows you to get access to data from previous Year / as stated previously this is a specific commercial option
Most TrustBuilder MFA offers are restricted to a 1 Year limit

Legacy and specific audit trail categories

The Audit Trail allows you to access the the following categories

V1 Audit Service (Legacy)

This category is the legacy Audit trail access. Evolutions will be made in the V2 API.

Deletion service for V2 Audit service

This service allows you to delete all Audit Entry lines for a login, in compliance with RGPD standards ( this deletion operation in itself will appear in the logs)

V2 My Audit Service

This category allows users to access their own activity / limited to the login which request this operation

V2 Audit Statistics Service

This category allows users to access a set of data used for the construction of statistics

V2 Export Audit endpoints, for Online and Archive Service

This category allows users to generate specific and timely exports

Characteristic of the unique identifier (ID) used in the log lines

The field used for data exports (ID) is constructed with the date and has the format YYYYMMDDHHmm *******
To export the day of May 13, for example, you will need to specify the following limits:

2020041300000000000
2020041390000000000

An identifier is therefore constructed from the date + random part (this random information is included in the log line)

Audit Trail logs contents

For each API call you will have a dedicate line within the logs with different information depending of the ACTION performed.
Some examples:

Someone creates a new account by using the API loginCreate
- It will generate the action CREATE_USER with some other information such as a Result: OK or KO
Someone deletes an account by using the API loginDelete:
- It will generate the action DELETE_USER with some other information such as a Result: OK or KO
Someone escalates privileges of another account by using the API loginUpdate:
- It will generate the action UPDATE_USER with some other information such as a Result: OK or KO and the new "role" of this user.
Certificate creation events by using the administration console:
- It will generate the action CREATE_CERTIFICATE with some other information related to this event
Successful authenticate events: You can have multiple successful event depending of the token used to authenticate
- Action CHECK_PUSH_RESULT with Result at OK
- Action AUTHORIZE_AUTHENTICATION at OK
- Action VALIDATE_OTP at OK
Failed authenticate events:
- Action CHECK_PUSH_RESULT with Result at KO
- Action AUTHORIZE_AUTHENTICATION with Result at KO
- Action VALIDATE_OTP with Result at KO

Audit Trail codes and descriptions

Each ACTION will come with some information such as:

Code	Description
ID	Unique ID
correlationId	ID to call the next logs starting from this point
date	date of the action
customerId	Unique ID of the customer
serviceId	Service ID
sourceIp	IP address source
targetAccount	Account targeted by the API action
targetLogin	Login targeted by the API action
action	Action performed
status	Results of the action performed
archiveData	Additional information for this log line in .json format
archiveDataType	Information related to the action. The content of this field may change depending of the action performed
troubleshootContext	Information to help troubleshoot in case of issue This field is removed in Archive Audit Trail
component	Internal name of component used to perform this API request
server	ID of the server who have handled the API request

The list of APIs and information logged can evolve

Audit Trail Actions and API calls

You will find below the list of APis call and the ACTION that will be logged in Audit Trail:

Action	Operation	Name (TRAIL)	Category
LOGIN_CREATE	CREATE_USER	loginCreate	Provisioning
LOGIN_UPDATE	UPDATE_USER	loginUpdate	Provisioning
LOGIN_DELETE	DELETE_USER	loginDelete	Provisioning
LOGIN_SEND_BY_MAIL	SENDMAIL	loginSendByMail	Provisioning
LOGIN_SEND_BY_SMS	SEND_SMS	loginSendBySms	Provisioning
LOGIN_ACTIVATE_CODE	ACTIVATE_CODE	loginActivateCode	Provisioning
LOGIN_GET_INFO_FROM_LINK	GET_CODE_FROM_LINK	loginGetInfoFromLink	Provisioning
LOGIN_GET_CODE_FROM_LINK	GET_CODE_FROM_LINK	loginGetCodeFromLink	Provisioning
LOGIN_RESET_PASSWORD_EXTENDED	GET_RESET_CODE	loginResetPwdExtended	Provisioning
LOGIN_RESET_PASSWORD	GET_RESET_CODE	loginResetPwd	Provisioning
LOGIN_RESET_PIN_ERROR_COUNTER	RESET_PIN_ERROR_COUNTER	loginResetPINErrorCounter	Provisioning
LOGIN_RESTORE	RESTORE_USER	loginRestore	Provisioning
LOGIN_ADD_DEVICE	GET_DEVICE_ACTIVATION_CODE	loginAddDevice	Provisioning
LOGIN_DELETE_TOOL	DELETE_DEVICE	loginDeleteTool	Provisioning
GROUP_ACCOUNT_CREATE	CREATE_MEMBERSHIP	groupAccountCreate	Provisioning
GROUP_ACCOUNT_UPDATE	UPDATE_MEMBERSHIP	groupAccountUpdate	Provisioning
GROUP_ACCOUNT_DELETE	DELETE_MEMBERSHIP	groupAccountDelete	Provisioning
SERVICE_CREATE	CREATE_SERVICE	serviceCreate	Configuration
SERVICE_UPDATE	UPDATE_SERVICE	serviceUpdate	Configuration
SERVICE_FEATURESET_UPDATE	UPDATE_SERVICE_FEATURESET	serviceFeaturesetUpdate	Configuration
SERVICE_CONFIGURATION_UPDATE	UPDATE_SERVICE_CONFIGURATION	serviceConfigurationUpdate	Configuration
SERVICE_BLOCK	BLOCK_SERVICE	serviceBlock	Configuration
CONNECTOR_ADD	CREATE_CONNECTOR	connectorAdd	Configuration
CONNECTOR_UPDATE	UPDATE_CONNECTOR	connectorUpdate	Configuration
CONNECTOR_DELETE	DELETE_CONNECTOR	connectorDelete	Configuration
SERVICE_GROUP_CREATE	CREATE_GROUP	serviceGroupCreate	Configuration
SERVICE_GROUP_UPDATE	UPDATE_GROUP	serviceGroupUpdate	Configuration
SERVICE_GROUP_DELETE	DELETE_GROUP	serviceGroupDelete	Configuration
SERVICE_FORM_CREATE	CREATE_SECURE_SITE	serviceFormCreate	Configuration
SERVICE_FORM_UPDATE	UPDATE_SECURE_SITE	serviceFormUpdate	Configuration
SERVICE_FORM_DELETE	DELETE_SECURE_SITE	serviceFormDelete	Configuration
SERVICE_POLICY_CREATE	CREATE_POLICY	servicePolicyCreate	Configuration
SERVICE_POLICY_UPDATE	UPDATE_POLICY	servicePolicyUpdate	Configuration
SERVICE_POLICY_DELETE	DELETE_POLICY	servicePolicyDelete	Configuration
SERVICE_ROLE_CREATE	CREATE_ROLE	serviceRoleCreate	Configuration
SERVICE_ROLE_UPDATE	UPDATE_ROLE	serviceRoleUpdate	Configuration
SERVICE_ROLE_DELETE	DELETE_ROLE	serviceRoleDelete	Configuration
CERTIFICATE_CREATE	CREATE_CERTIFICATE	certificateCreate	Configuration
CERTIFICATE_UPDATE	UPDATE_CERTIFICATE	certificateUpdate	Configuration
CERTIFICATE_DELETE	DELETE_CERTIFICATE	certificateDelete	Configuration
RADIUS_ADD	CREATE_RADIUS	radiusAdd	Configuration
RADIUS_DELETE	DELETE_RADIUS	radiusDelete	Configuration
AUTHENTICATE	VALIDATE_OTP	authenticate	Authentication
AUTHENTICATE_WITH_IP	VALIDATE_OTP	authenticateWithIp	Authentication
AUTHENTICATE_RADIUS	VALIDATE_OTP	authenticateRadius	Authentication
AUTHENTICATE_EXTENDED	VALIDATE_OTP	authenticateExtended	Authentication
PUSH_AUTHENTICATE	SEND_PUSH_REQUEST	pushAuthenticate	Authentication
CHECK_PUSH_RESULT	CHECK_PUSH_RESULT	checkPushResult	Authentication
SEAL_VERIFY	VALIDATE_SEAL	sealVerify	Authentication
SEAL_DEFERRED_VERIFY	DEFERRED_VALIDATE_SEAL	sealDeferredVerify	Authentication
OTP	GENERATE_OTP	otp_finalize	Devices
ACTIVATE	ACTIVATE	activate_finalize	Devices
RESET	RESET	reset_finalize	Devices
PUSH_OTP	PUSH_VALIDATION	pushOtp_finalize	Devices
PUSH_ACTIVATE	PUSH_ACTIVATION	pushActivateCa_finalize	Devices
SEAL	GENERATE_SEAL	seal_finalize	Devices
LOGINS_MIGRATE_PASSWORDS	MIGRATE_PASSWORDS	loginsMigratePasswords	Undefined provisioning
USER_RETURNING_GET_CODE_FROM_LINK	GET_RETURNING_CODE_FROM_LINK	userReturningGetCodeFromLink	Undefined provisioning
GROUP_FORM_CREATE	CREATE_GROUP_FORM	groupFormCreate	Undefined configuration
GROUP_FORM_DELETE	DELETE_GROUP_FORM	groupFormDelete	Undefined configuration
SERVICE_DELETE	DELETE_SERVICE	serviceDelete	Undefined configuration
CUSTOMER_CREATE	CREATE_CUSTOMER	customerCreate	Undefined configuration
CUSTOMER_UPDATE	UPDATE_CUSTOMER	customerUpdate	Undefined configuration
CUSTOMER_DELETE	DELETE_CUSTOMER	customerDelete	Undefined configuration
PUSH_SEAL	PUSH_SEAL	pushSeal	Undefined authentication
LOGIN_MACCESS_DELETE	DELETE_USER_MACCESS	loginMaccessDelete	Undefined authentication
ADD_SERVICE	ADD_SERVICE	addService_finalize	Undefined devices
SYNCHRONIZE	SYNCHRONIZE	synchro_finalize	Undefined devices
MS	MS	ms_finalize	Undefined devices
ACTIVATE_TB	ACTIVATE_TB	activateTB_finalize	Undefined devices
CHECK_PUSH	CHECK_PUSH	checkPush_finalize	Undefined devices
PASSWORD	PASSWORD	password_finalize	Undefined devices
PUSH_REGISTRATION	PUSH_REGISTRATION	pushRegistration_finalize	Undefined devices
MESSAGES	MESSAGES	messages_finalize	Undefined devices
NEW_SN	NEW_SN	newsn_finalize	Undefined devices
GET_SN	GET_SN	getsn_finalize	Undefined devices
SET_BIOKEY	SET_BIOKEY	setBiokey_finalize	Undefined devices
STATUS	STATUS	status_finalize	Undefined devices
PUSH_OTP_REQUEST	PUSH_OTP_REQUEST	pushOtpRequest_finalize	Undefined devices
PUSH_OTP_GET_RESULT	PUSH_OTP_GET_RESULT	pushOtpGetResult_finalize	Undefined devices
PUSH_ACTIVATION_REQUEST	PUSH_ACTIVATION_REQUEST	pushActivationRequest_finalize	Undefined devices
PUSH_ACTIVATION_GET_CODE	PUSH_ACTIVATION_GET_CODE	pushActivationGetCode_finalize	Undefined devices
FORGOT_PASSWORD	FORGOT_PASSWORD	forgotPassword_finalize	Undefined devices
EMAIL_RECOVERY	EMAIL_RECOVERY	emailRecovery_finalize	Undefined devices
CHECK_LOGIN	CHECK_LOGIN	checkLogin_finalize	Undefined devices
UPGRADE	UPGRADE	upgrade_finalize	Undefined devices
DISCONNECT	DISCONNECT	disconnect_finalize	Undefined devices
EXPORT	EXPORT	export_finalize	Undefined devices
SET_PASSWORD	SET_PASSWORD	setPassword_finalize	Undefined devices
PRE_AUTH	PRE_AUTH	preauth_finalize	Undefined devices
PUSH_REMOTE_OTP_GET_RESULT	PUSH_REMOTE_OTP_GET_RESULT	pushRemoteOtpGetResult_finalize	Undefined devices
PUSH_REMOTE_OTP_RESULT	PUSH_REMOTE_OTP_RESULT	pushRemoteOtpRequest_finalize	Undefined devices

The list of APIs and information logged can evolve

Potential key <-> value generated depending of the APIsI

Each API will generate an action with complementary information in the archiveData and troubleshootContext fields such as

Field	Comments
id	Unique ID
serviceId	Service ID
login	login of the user
date	date of the action
method	When calling the TrustBuilder MFA API / Method used in the operation
errcode	When calling the TrustBuilder MFA API / API Return Code / OK / NOK or Specific ErrorCode of a call
tooltype	if indicated type of TrustBuilder MFA or Web Application used for a call (Authenticator...)
toolversion	if indicated version of TrustBuilder MFA or Web Application used for a call
toollibversion	Version of the TrustBuilder MFA library used by this Application
toolplatform	Authentication plateform and mode used
useripaddr	When available, User IP address indicated in the request
role	Role information in the performed operation (Administration console)
createdby	Role Id
adminLogin	For Administration console operation / Administrator Login who performed this operation
objectInfo	Information about the action (label certificate for example)
apiVersion	Version of the TrustBuilder MFA API called in this operation
deviceType	Type of Device used, Android, iPhone,
deviceAlias	If indicated the Alias of the device used in the operation
deviceName	if indicated Name of the end-device Mobile / Workstation
deviceVersion	if indicated Version of the end-device Mobile / Workstation
deviceLibVersion	if indicated Lib version used on the end-device Mobile / Workstation
secondFactor	Second Factor used
serviceName	Name of the service, displayed during user operations
userAgent	if available "userAgent" information of Browser / Internet Application used
withoutPinForced	Settings "Without PIN" Forced in Site parameters for chosen Secure site
sealedData	sealedData information used in specific API call
extraFields	if used in the operation "Extrafields" / option to add Extra Fields in the user profile
lang	Language Attribute in User profile to display operation
codeType	Type of code created for Activations
rejectReason	When failing, indicated reason if directly available in error codes
roleId	When Provisioning operation RoleID used for updating user roles
roleName	When Provisioning operation name of the role used for updating user roles
certId	TrustBuilder MFA Certificate ID used in API call (generated in the Administration console)

The list of APIs and information logged can evolve