Keyavi API Documentation

Keyavi's APIs allow developers to create custom integrations with Keyavi's platform and other tools and technologies. The Keyavi API follows REST architecture. The API uses standard HTTP verbs and resource-oriented URLs, returns JSON for all requests, and responds with standard HTTP codes to indicate the success or failure of requests.

Getting started

To get started quickly with the Keyavi APIs, review the high-level steps below and follow the instructions in the linked sections.

1. Work with your system administrator to ensure they configure API access and grant the API users appropriate privileges.

2. Get the credentials to authenticate with the Keyavi API, including the client_id, client_secret, and tenant_id.

3. Authenticate with the identity provider configured in your organization to get a Bearer token for subsequent requests.

4. Make your first call to one of the available resources

Authentication

All requests to Keyavi API must be authenticated. The Keyavi API supports OAuth2.0 and OpenID Connect via the Microsoft Azure Active Directory (Azure AAD) platform. By using the authentication libraries for Azure AAD, integrations authenticate identities and acquire bearer tokens to access protected APIs.

Each request is associated with the authenticated API user. You can authenticate as an API user in one of two ways: as a client app or as an individual user. For client app access, you'll use the client_credentials grant type; for user access, you'll use the password grant type.

To connect with Keyavi's APIs, ensure that your system administrator configured in the Web API in Azure AAD. Work with your system administrator to acquire the Azure AAD tenant ID, client ID, client secret (for app-based access), and the scope's address.

note

Authentication via API does not change what the authenticated user has access to. Authentication verifies who the API user is, while Keyavi's role-based access determines what data the API user can access. Work with your Keyavi administrator to ensure the API user has appropriate permissions.

Authentication with client credentials

To authenticate an app using client credentials:

1. Send an HTTP POST request to the Microsoft Online OAuth 2.0 token endpoint with the appropriate parameters. The endpoint URL is https://login.microsoftonline.com/{tenant-id}>/oauth2/v2.0/token, where {tenant-id} is your Azure Active Directory tenant ID. Include these parameters in the request body:

   • grant_type: Use client_credentials.
   • client_id: Use the client ID of your Keyavi configuration.
   • client_secret: Use the client secret of your Keyavi configuration.
   • scope: Use the scope address of your Keyavi configuration with /.default appended to the end of the address.

   curl --location 'https://login.microsoftonline.com/<Your Tenant ID>/oauth2/v2.0/token' \
   --data-urlencode 'grant_type=client_credentials' \
   --data-urlencode 'client_id=<Your client ID>' \
   --data-urlencode 'client_secret=<Your client secret>' \
   --data-urlencode 'scope=api://<Your scope address>/.default' \

   If the authentication succeeds, the token endpoint returns a JSON response that includes a bearer token.

2. Copy the secret to a secure place. Store the bearer token securely and in a safe place.

   Note: Anyone with this token can perform the authorized actions against the resources that the token has access to.

3. Use this token to authenticate future API requests by including this header:

   Authorization: Bearer [access_token]

Authentication with user credentials

To authenticate a user using their user name and password:

1. Send an HTTP POST request to the Microsoft Online OAuth 2.0 token endpoint with the appropriate parameters. The endpoint URL is https://login.microsoftonline.com/{tenant-id}>/oauth2/v2.0/token, where {tenant-id} is your Azure Active Directory tenant ID. Include these parameters in the request body:

   • grant_type: Use password.
   • client_id: Use the client ID of your Keyavi configuration.
   • scope: Use the scope address of your Keyavi configuration with /access_as_user appended to the end of the address.
   • username: Use your Keyavi user name.
   • password: Use your Keyavi password.

   curl --location 'https://login.microsoftonline.com/{tenant-id}>/oauth2/v2.0/token' \
   --data-urlencode 'grant_type=password' \
   --data-urlencode 'client_id=<Your client ID>' \
   --data-urlencode 'scope=api://<Your scope address>/access_as_user' \
   --data-urlencode 'username=<Your user name>' \
   --data-urlencode 'password=<Your password>'

   If the authentication succeeds, the token endpoint responds with a JSON response that includes a bearer token.

2. Copy the secret to a secure place. Store the bearer token securely and in a safe place.

   Note: Anyone with this token can perform the authorized actions against the resources that the token has access to.

3. Use this token to authenticate future API requests by including this header:

   Authorization: Bearer [access_token]

HTTP requests

After you authenticate and successfully receive a bearer token, you're ready to make requests to the Keyavi API.

Keyavi APIs only accept HTTPS traffic. Requests to the Keyavi API are composed of:

• The base URL which provides the starting point for all requests. Keyavi's base URL is https://<Custom API URL>/api/. The base URL for each environment is configured during Keyavi implementation.
• The endpoint which represents the address of the resource you're connecting to. See the API Reference for the endpoints of each URL. The terms endpoint and resource are often used interchangeably, but in these API docs, we only use endpoint when discussing the request URL.
• The HTTP header must always include the bearer token from the initial authorization request.
• Optional query parameters which allow sorting, filtering, and limiting data. See Filtering and sorting and Pagination for details about using query parameters.

Here's an example request to the full-payload resource, which is specified by the /logs/full-payload endpoint with a single Authorization header that includes the Bearer token.

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

Resources

A resource is an entity with associated data, relationships to other resources, and a set of methods that operate on it. For example, you can audit the Keyavi-protected files using the logs/full-payload or logs/payload resources.

The Keyavi APIs include the following resources:

Resource	Description
logs/full-payload	Retrieves all the events associated with file protect, open, and audit events. Returns sensitive information (physical location where the event was triggered from). The resource returns Personally Identifiable Information (PII).
logs/payload	Retrieves all the events associated with file protect, open, and audit events. Returns sensitive information (physical location where the event was triggered from). The resource does not return Personally Identifiable Information (PII).

Filtering and sorting

Keyavi resources often return large amounts of data that you can filter to produce a specific subset of records. Keyavi APIs use query parameters to filter data in requests.

Query parameters are additional parameters that you add to the API endpoint URL. You can use query parameters to filter, sort, or limit the data returned. Add query parameters to the end of the endpoint URL after a question mark (?). This example filters log/payload resources to show only files with Audit actions.

curl --location 'https://<Custom API URL>/api/logs/payload?actionAttempted=Audit' \
--header 'Authorization: Bearer <Your Token>'

You can add more filters by separating queries using and ampersand & to separate parameters, like in this example:

curl --location 'https://<Custom API URL>/api/logs/payload?actionAttempted=Audit&result=RevokeAccess' \
--header 'Authorization: Bearer <Your Token>'

Filter options differ for each resource. See the Parameters section for specific resources in the API Reference.

Pagination

Keyavi resources that return large amounts of data support pagination to break down large amounts of data into smaller, more manageable chunks.

Keyavi APIs implement pagination through a JSON object called pagination. The pagination object contains the following properties:

• totalRecords: The total number of records available in the dataset.
• pageSize: The maximum number of records returned per page.
• itemsInPage: The number of records returned on the current page.
• page: The current page number.

You can request specific pages by passing the page number as a query parameter. This example returns page 5 from the full-payload resource.

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

Audit & Forensics Logs Actions, Results, and Reasons

The Paylod and Full Payload objects include attributes to describe the action taken on a file (actionAttempted), how Keyavi responded to the action (result), and the reason for the response (resultReason).

Values for actionAttempted include:

• Encrypt
• Decrypt
• Audit
• EncryptionRequest

Encrypt Action

Encrypt can return the following values for result and resultReason.

result	resultReason
AccessGranted	Success
AccessDenied	GeoValidationCountryExclusionFailed

Decrypt Action

Decrypt can return the following values for result and resultReason.

result	resultReason
AccessGranted	Success
AccessDenied	GeoValidationCountryExclusionFailed, TimeEmbargoFailed, UserPayloadNoAccess, or GeoValidationFailed

Audit Action

Audit can return the following values for result and resultReason.

result	resultReason
AccessWindow	Changed or Created
RevokeAccess	Changed
AuthorisedGroupAccess	Changed or Created
AuthorisedUserAccess	Changed or Created
AuthorChanged	Changed

Encryption Request Action

EncryptionRequest can return the following values for result and resultReason.

result	resultReason
AccessDenied	GeoValidationCountryExclusionFailed or GeoValidationFailed