Keyavi API Reference

The Keyavi Audit & Forensics Logs API provides read-only access to forensics and audit data that Keyavi nodes collect. These APIs provide the ability to integrate Keyavi with external applications, such as SIEM solutions like Microsoft Sentinel. The Audit and Forensics logs API includes two resources: logs/payload and logs/full-payload. The primary difference between the two is logs/payload does not return Personally Identifiable Information (PII), while logs/full-payload does.

full-payload

The full-payload endpoint contains all the events associated with a file, including protectClosed The process of encrypting a file and tying access policies to it so that authorized users can access the data securely based on restrictions set by the data owner., openClosed The process of decrypting a protected, encrypted file and transforming it back into its original, accessible form for authorized users based on policies set for that file., and audit events. It includes PII and sensitive information, like names and email addresses. If you do not want to return PII, use the payload resource instead.

The Full Payload Object

Copy 
{
    "pagination": {
        "totalRecords": 26381,
        "pageSize": 100,
        "itemsInPage": 100,
        "page": 1
    },
    "data": [
        {
            "userLastNameFirstName": "Smith,John",
            "userEmailAddress": "[email protected]",
            "currentOwnerLastNameFirstName": "Smith,Adam",
            "currentOwnerEmailAddress": "[email protected]",
            "logId": 12345,
            "userId": "userId-u07a-4ubd-j6xd-7611s406omvy",
            "payloadId": "payloadId-i43t-2noi-x9sg-0356e721jcmw",
            "payloadName": "document.txt",
            "currentPayloadOwnerId": "ownerId-v92w-1scm-t5kv-4191q211jqnp",
            "actionAttempted": "Decrypt",
            "result": "AccessDenied",
            "resultReason": "UserPayloadNoAccess",
            "logTimestamp": "2023-05-05T15:54:22.5071276",
            "userNetwork": {
                "ipAddress": "10.10.10.1",
                "networkName": "Network",
                "networkId": "networkId-a65d-6peq-c6uy-5887t707yegg",
                "domainName": "AzureAD",
                "deviceType": "Microsoft Windows 10 Enterprise",
                "machineName": "Machine",
                "mac": "macy273pepe",
                "uuid": "uuId-y66n-6vpe-r3uk-9252d322hasf",
                "serviceProvider": "",
                "latLong": "84.9183,-09.7229",
                "address": "760 Main Street, Paris, CO 80000, USA"
            }
        },
    ]
}

Full-Payload Attributes

The following table lists the attributes of this object.

What's included in the JSON object depends on the permissions assigned to the API user. Work with your administrator to ensure that you have the right permissions.

Attribute

Description

pagination

object

Provides pagination details. You can pass page and pageSize query parameters to control the amount of data you receive.

data

array

Contains the attributes and values of the object retrieved.

logID

string

 The unique identifier of the log record in Keyavi.

userLastNameFirstName

string

The full name of the user associated with the logged record, formatted as LastName, FirstName.

userLastNameFirstName is PII.

userEmailAddress

string

The email address of the user associated with the log record.

userEmailAddress is PII.

currentOwnerLastNameFirstName

string

The first and last name of the user permitted to manage the policiesClosed Rules associated with a protected payload that designate which users can access the encrypted file, from what locations, and for what time periods. of the Keyavi-protected file (the owner).

currentOwnerLastNameFirstName is PII.

currentOwnerEmailAddress

string

The email address of the user permitted to manage the policies of the Keyavi-protected file (the owner).

currentOwnerEmailAddress is PII.

userId

string

The unique identifier of the user associated with the log record. This is a Keyavi-generated internal user identifier unique to a Keyavi node.

payloadId

string

The unique identifier associated with the Keyavi-protected file. This is a Keyavi-generated internal payloadClosed A database entry that carries metadata, access rules, and codes to make possible the protection and controlled sharing of data by authorized users according to the data owner's policies. Payloads enable granular data protection without moving data outside the organization's control. identifier unique to a Keyavi node.

payloadName

string

The name of the Keyavi-protected file.

currentPayloadOwnerId

string

The unique identifier of the user permitted to manage the policies of the Keyavi-protected file (the owner).

actionAttempted

string

The type of logged action (e.g., Decrypt, Audit, Encrypt, DecryptLocal, StartSession, EndpointCall, Unknown, or EncryptionRequest). The actionAttempted always includes a related result and resultReason. See Audit & Forensics Logs Actions, Results, and Reasons for details.

result

string

How Keyavi responded to the actionAttempted. Possible values include AccessGranted, AccessDenied, AccessWindow, RevokeAccess, AuthorisedGroupAccess, AuthorisedUserAccess, Unknown, or AuthorChanged. See Audit & Forensics Logs Actions, Results, and Reasons for details.

resultReason

string

Why Keyavi returned the result of the actionAttempted. Possible values include Changed, Created, Success, TimeEmbargoFailed, UserPayloadNoAccess, Unknown, GeoValidationCountryExclusionFailed, PayloadRecalled, UserSuspended, TorNotAuthorized, ValidationIncomplete, LocationMismatch, or GeoValidationFailed. See Audit & Forensics Logs Actions, Results, and Reasons for details.

logTimestamp

string

The UTC date and time of the log record, formatted as an ISO 8601 date and time: YYYY-MM-DDTHH:MM:SS.ss.

userNetwork

string

The network information used to identify geolocationClosed The ability to track a device’s physical whereabouts down to latitude and longitude coordinates, or more practically, a physical address, using GPS, cell phone towers, WiFi access points and IP address lookup, or a combination of these. information for the user's network, including IP address, network name, network ID, domain name, device type, machine name, MAC address, UUID, service provider, latitude and longitude, and address.

Access to geolocation information requires elevated privileges.

oId

string

The identity provider's unique identifier for a user authenticating with Keyavi using credentials from an external IdP. The value is null for user's authenticating with credentials managed by their organization.

oIdProviderName

string

The name of the identity provider associated with the oId.

Retrieve Full-Payload

Use a GET /logs/full-payload request to retrieve the list of logged events, based on the authentication used to make the request.

Copy 
curl --location 'https://<Custom API URL>/api/logs/full-payload' \
--header 'Authorization: Bearer <Your Token>'

Parameters

The following table shows the query parameters available to tailor and filter the response for this resource.

Parameter

Description

actionAttempted

string

Filter by Decrypt, Audit, Encrypt, DecryptLocal, StartSession, EndpointCall, Unknown, or EncryptionRequest .

currentPayloadOwnerId

string

Filter by the unique identifier of the owner of the Keyavi-protected file.

endTime

string

Filter by the concluding time and date of any file contained in the query to retrieve records modified before a specific timestamp. Use ISO 8601 format, such as YYYY-MM-DDTHH:MM:SS.ss.

page

integer

Specify the desired page number to return from a paginated dataset.

pageSize

integer

Specify the number of records per page from a paginated dataset. The default pageSize is 100.

payloadId

string

Filter by the unique identifier of the Keyavi-protected file.

payloadName

string

Filter by the name of the Keyavi-protected file.

result

string

Filter by AccessGranted, AccessDenied, AccessWindow, RevokeAccess, AuthorisedGroupAccess, AuthorisedUserAccess, Unknown, or AuthorChanged.

resultReason

string

Filter by Changed, Created, Success, TimeEmbargoFailed, UserPayloadNoAccess, UserSuspended, TorNotAuthorized, ValidationIncomplete, LocationMismatch, Unknown, GeoValidationCountryExclusionFailed, PayloadRecalled, or GeoValidationFailed.

userId

string

Filter by the unique identifier of the user associated with the log record.

sort

string

Sort the results by logTimestamp, userLastNameFirstName, result, resultReason, actionAttempted, AppId, EndpointName,or payloadName. To order ascending, prepend with +; to order descending, prepend with -. For example, ?sort=-logTimestamp returns a descending list sorted by logTimestamp.

startTime

string

Filter by the beginning time and date of any file contained in the query to retrieve records modified after a specific timestamp. Use ISO 8601 format, such as YYYY-MM-DDTHH:MM:SS.ss.

Payload

The payload endpoint contains all the events associated with a file, including protect, open, and audit events. it does not include PII or sensitive information like names and email addresses. If you want to return PII, use the full-payload resource instead.

The Payload Object

Copy 
{
  "pagination": {
    "totalRecords": 13,
    "pageSize": 15,
    "itemsInPage": 13,
    "page": 1
  },
  "data": [
    {
     "logId": 12345,
     "userId": "userId-m21z-5ofr-i2hy-3226q472izwv",
     "payloadId": "payloadId-h97c-8jdh-w7ky-6186r968vjee",
     "payloadName": "Document.ppt",
     "currentPayloadOwnerId": "ownerId-d98l-4znh-y3kn-9760h914fdmu",
     "actionAttempted": "Decrypt",
     "result": "AccessDenied",
     "resultReason": "UserPayloadNoAccess",
     "logTimestamp": "2023-05-05T15:54:22.5071276",
     "userNetwork": {
        "ipAddress": "10.10.10.1",
        "networkName": "Network",
        "networkId": "networkId-l16b-8dxi-e0be-4078j151qjfe",
        "domainName": "AzureAD",
        "deviceType": "Microsoft Windows 10 Enterprise",
        "machineName": "Machine",
        "mac": "macy273pepe",
        "uuid": "uuId-p80v-7wbe-h4yo-3952v555hhty",
        "serviceProvider": "",
        "latLong": "84.9183,-09.7229",
        "address": "760 Main Street, Paris, CO 80000, USA"
     }
    }
   ]
 }

Payload Attributes

The following table lists the attributes of this resource.

What's included in the JSON object depends on the permissions assigned to the API user. Work with your administrator to ensure that you have the right permissions.

Attribute

Description

pagination

object

Provides pagination details. You can pass page and pageSize query parameters to control the amount of data you receive.

data

array

Contains the attributes and values of the object retrieved.

logID

string

The unique identifier of the log record in Keyavi.

userId

string

The unique identifier of the user associated with the log record. This is a Keyavi-generated internal user identifier unique to a Keyavi node.

payloadId

string

The unique identifier associated with the Keyavi-protected file. This is a Keyavi-generated internal payload identifier unique to a Keyavi node.

payloadName

string

The name of the Keyavi-protected file.

currentPayloadOwnerId

string

The unique identifier of the user permitted to manage the policies of the Keyavi-protected file (the owner).

actionAttempted

string

The type of logged action (e.g., Decrypt, Audit, Encrypt, DecryptLocal, StartSession, EndpointCall, Unknown, or EncryptionRequest). The actionAttempted always includes a related result and resultReason. See Audit & Forensics Logs Actions, Results, and Reasons for details.

result

string

How Keyavi responded to the actionAttempted. Possible values include AccessGranted, AccessDenied, AccessWindow, RevokeAccess, AuthorisedGroupAccess, AuthorisedUserAccess, Unknown, or AuthorChanged. See Audit & Forensics Logs Actions, Results, and Reasons for details.

resultReason

string

Why Keyavi returned the result of the actionAttempted. Possible values include Changed, Created, Success, TimeEmbargoFailed, UserPayloadNoAccess, Unknown, GeoValidationCountryExclusionFailed, PayloadRecalled, UserSuspended, TorNotAuthorized, ValidationIncomplete, LocationMismatch, or GeoValidationFailed. See Audit & Forensics Logs Actions, Results, and Reasons for details.

logTimestamp

string

The UTC date and time of the log record, formatted as an ISO 8601 date and time: YYYY-MM-DDTHH:MM:SS.ss.

userNetwork

object

The network information used to identify geolocation information for the user's network, including IP address, network name, network ID, domain name, device type, machine name, MAC address, UUID, service provider, latitude and longitude, and address.

Access to geolocation information requires elevated privileges.

oId

string

The identity provider's unique identifier for a user authenticating with Keyavi using credentials from an external IdP. The value is null for user's authenticating with credentials managed by their organization.

oIdProviderName

string

The name of the identity provider associated with the oId.

Retrieve Payload

Use a GET /logs/payload request to retrieve the list of logged events, based on the authentication used to make the request.

Copy 
curl --location 'https://<Custom API URL>/api/logs/full-payload' \
--header 'Authorization: Bearer <Your Token>'

Parameters

The following table shows the query parameters available to tailor and filter the response for this resource.

Parameter

Description

actionAttempted

string

Filter by Decrypt, Audit, Encrypt, DecryptLocal, StartSession, EndpointCall, Unknown, or EncryptionRequest .

currentPayloadOwnerId

string

Filter by the unique identifier of the owner of the Keyavi-protected file.

endTime

string

Filter by the concluding time and date of any file contained in the query to retrieve records modified before a specific timestamp. Use ISO 8601 format, such as YYYY-MM-DDTHH:MM:SS.ss.

page

integer

Specify the desired page number to return from a paginated dataset.

pageSize

integer

Specify the number of records per page from a paginated dataset. The default pageSize is 100.

payloadId

string

Filter by the unique identifier of the Keyavi-protected file.

payloadName

string

Filter by the name of the Keyavi-protected file.

result

string

Filter by AccessGranted, AccessDenied, AccessWindow, RevokeAccess, AuthorisedGroupAccess, AuthorisedUserAccess, Unknown, or AuthorChanged.

resultReason

string

Filter by Changed, Created, Success, TimeEmbargoFailed, UserPayloadNoAccess, UserSuspended, TorNotAuthorized, ValidationIncomplete, LocationMismatch, Unknown, GeoValidationCountryExclusionFailed, PayloadRecalled, or GeoValidationFailed.

userId

string

Filter by the unique identifier of the user associated with the log record.

sort

string

Sort the results by logTimestamp, userLastNameFirstName, result, resultReason, actionAttempted, AppId, EndpointName,or payloadName. To order ascending, prepend with +; to order descending, prepend with -. For example, ?sort=-logTimestamp returns a descending list sorted by logTimestamp.

startTime

string

Filter by the beginning time and date of any file contained in the query to retrieve records modified after a specific timestamp. Use ISO 8601 format, such as YYYY-MM-DDTHH:MM:SS.ss.