Resource Access Log

About

The Trusted Twin platform allows you to log data about access to resources in your account by your own account (personal account) as well as foreign accounts. The data is stored in the form of a user-defined Timeseries table.

In order to use the Resource Access Log to log access to resources in your account:

1. Create a Timeseries table* where the Resource Access Log data is to be stored (see Timeseries configuration section);
2. Configure the Resource Access Log represented by the previously defined Timeseries table for the account (see Account configuration section).

You can create multiple Timeseries tables to log the access to resources in your account.

Each of the tables needs to be added to the account's configuration (through the update_account endpoint). For more details, please see the Enabling Resource Access Log section.

*

Please note that Timeseries is a Trusted Twin advance database service, and it needs to be enabled for an account. Please get in touch with hello@trustedtwin.com to enable the advanced database services for your account.

Timeseries configuration

The Resource Access Log is stored in a user-defined Timeseries table. You can create a Timeseries table via the create_timeseries_table endpoint.

Please refer to Resource Access Log template variables for template variables available for the Resource Access Log templates.

Example configuration

Below you can find an example of a request body used to create a Timeseries table used to store the Resource Access Log:

In order to access the Timeseries database, please follow the steps in the Database services access article.

Template variables

In the below sections you can find variables available for the Resource Access Log divided into categories with examples. The examples are based on the Timeseries configuration provided in the Example configuration section above.

Request variables

Variable	Column name	Description
request_uuid	request_uuid	Request UUID.
request_ts	request_ts	Timestamp of the request. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
operation	operation	Name of the operation.
status_code	status_code	Status of the request.
RESOURCES	resources	Resource passed in the request.
PARAMS	params	Query string parameters passed in the request.

Example

request_uuid	request_ts	operation	status_code	resources	params
74239fad-816e-4e75-b6fd-d4a4c50df0d2	1704184875.00	get_twin	200	{"twin": "78772552-f372-4cce-ac36-247af4bcb95c"}	{"show_terminated": "false"}

Requestor variables

Variable	Column name	Description
account	account	Account UUID of the requestor.
role	role	Role UUID of the requestor.
user	user	User UUID of the requestor.

Example

account	role	user
20db3819-4cc2-44b5-bba5-fb270f105c07	27295dc1-bfbf-43bd-870c-bce2a1ff942e	ed32777c-efe6-4fac-b1fd-0c17b6a6c9ce

Authentication variables

Variable	Column name	Description
auth_type	auth_type	Denotes the authentication used. It can be either secret for authentication performed with a user secret or token for authentication performed with a user token.
auth_fingerprint	auth_fingerprint	4 last characters of the User Secret of the calling user or the User Secret that was used to generate the User Token of the calling user.
auth_validity_ts	auth_validity_ts	Validity of the User Secret or the User Token of the calling user. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).

Example

auth_type	auth_fingerprint	auth_validity_ts
user	xds8	1735821675.00
token	xds8	1735821675.00

Twin variables

Variable	Column name	Description
twin	twin	Twin UUID of the requestor.
twin_status	twin_status	Status of a Twin. Value can be "alive" or "terminated".
twin_creator	twin_creator	Account UUID of the account that created the Twin.
twin_owner	twin_owner	Account UUID of the account which is the current owner of the Twin.
twin_created_ts	twin_created_ts	Time at which the Twin was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
twin_updated_ts	twin_updated_ts	Time at which the Twin was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).

Example

twin	twin_status	twin_creator	twin_owner	twin_created_ts	twin_updated_ts
e2a2d605-8f87-40a9-a8c6-80b1309860ac	alive	a517cacf-6819-4c24-a4c9-934678f66c81	a517cacf-6819-4c24-a4c9-934678f66c81	1722598875.00	1725461001.00

Ledger variables

Variable	Column name	Description
LEDGER	ledger	Dictionary where keys are names of Entries and values denote whether the requestor could read the Entry's value ("ok") or whether the value was not accessible to the requestor ("error").

Example

ledger
{ "entry_1": "ok", "entry_2": "error"}

Doc variables

Variable	Column name	Description
DOCS	docs	Dictionary where the key is the name of the Doc and the value is a dictionary containing Doc creation timestamp ("doc_created_ts") and timestamp of last Doc update ("doc_updated_ts").

Example

docs
{ "doc_name_1": {"doc_created_ts": "1702934158.00", "doc_updated_ts": "1703020558.00"}}

Resources and operations logged

The Resource Access Log can be configured to log access to the following resources for the following operations:

Resource	Operation	Personal account	Foreign account	Template variables
Twin	create_twin	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	get_twin	✓	✓	request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	update_twin	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	terminate_twin	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	create_twin_identity	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	get_twin_identity	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	update_twin_identity	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin	delete_twin_identity	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin, Ledger	add_twin_ledger_entry	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts
Twin, Ledger, Entry	get_twin_ledger_entry	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, LEDGER
Twin, Ledger, Entry	get_twin_ledger_entry_value	✓	✓	request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, LEDGER
Twin, Ledger, Entry	update_twin_ledger_entry	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, LEDGER
Twin, Ledger, Entry	update_twin_ledger_entry_value	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, LEDGER
Twin, Ledger, Entry	update_twin_ledger_entry_ref_value	✓		request_uuid, request_ts, account, operation, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, LEDGER
Twin, Ledger, Entry	delete_twin_ledger_entry	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, LEDGER
Twin	attach_twin_doc	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, DOCS
Twin, Doc	get_twin_doc	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, DOCS
Twin, Doc	update_twin_doc	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, DOCS
Twin, Doc	delete_twin_doc	✓		request_uuid, request_ts, account, role, user, auth_type, auth_fingerprint, auth_validity_ts, operation, status_code, RESOURCES, PARAMS, twin, twin_status, twin_owner, twin_creator, twin_created_ts, twin_updated_ts, DOCS

Account configuration

Enabling Resource Access Log

The Resource Access Log is enabled at the account-level through adding the "resource_access_log" property when updating the account (update_account).

Updating Resource Access log

The Resource Access Log can be updated through the update_account endpoint. The new request body will replace the content of the "resource_access_log" attribute.

Disabling Resource Access Log

The Resource Access Log functionality can be disabled by setting the value of the "resource_access_log" property to "null" through the update_account endpoint.