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

To access Keyavi APIs, you need to include a subscription key in the headers of your HTTP requests. The subscription key ensures secure and authorized access to the API.

To obtain a subscription key, contact your Keyavi representative. After you're issued a subscription key, you'll receive an email with everything you need.

Including Your Subscription Key in Requests

Include the subscription key (Ocp-Apim-Subscription-Key)in the headers of your HTTP requests as follows:

Copy 
curl --location 'https://<<span class="mc-variable General.Company-name variable">Keyavi</span>-API-URL>/api/endpoint' \
--header 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Replace YOUR_SUBSCRIPTION_KEY with the actual subscription key obtained from the developer portal.

Managing Your Subscription Key

Manage your subscription key in the Keyavi Developer Portal. There you can view your subscription keys and regenerate them if needed.

Be sure to keep your subscription key secure and never share it publicly. Treat your subscription key like a password and keep it confidential. If you suspect that your subscription key has been compromised, regenerate it in the developer portal.

    • 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' \

HTTP Requests

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 varies depending on the environment you access (e.g., production, sandbox, or UAT.) The Developer Portal is in a sandbox environment, and the base URL is https://apimg-Keyavidev.azure-api.net/Keyavi-public/v2/api/.

  • 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 subscription key. All logged calls (e.g., those that create or update data) must also include the x-api-caller-id, which is the user id of the person or service making the 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 with the required headers for a call to the protect-remote resource.

Copy 
curl --location 'https://<<span class="mc-variable General.Company-name variable">Keyavi</span>-API-URL>/api/payloads/protect-remote/' \
--header 'x-api-caller-id: <USER-ID>' \
--header 'Ocp-Apim-Subscription-Key: <YOUR-SUBSCRIPTION-KEY>' \

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

payloadsClosed 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.

Payloads are Keyavi-protected files or data. Each payload consists of the file or data and metadata about it, like who the owner is, which users aor groups can access it, and at what level they can access it. Use the payloads resource to create, 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 assign policiesClosed Rules associated with a protected payload that designate which users can access the encrypted file, from what locations, and for what time periods. to users or groups.

users

Users are the individuals to whom you can grant access to payloads or manage in groups. Use the users resource to get user information needed to assign policies with the payloads resource, or to manage user details.

groups

Groups are collections of users to whom you can grant access to payloads. Use the groups resource to get group information needed to assign policies with the payloads resource, or to manage group details.

logs

Logs provide audit and forensics information. Use logs/payload and logs/full-payload to retrieve details about all the events associated with file protect, open, and audit events.

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.

Copy 
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:

Copy 
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.

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

Users, Roles, and Permissions

Permissions define what activities an authorized userClosed A recipient with access to the secured data file. The data owner defines the authorized users. can perform on a given endpoint. Keyavi provides predefined roles that include the permissions needed to perform certain tasks. Each user in your organization is assigned one or more roles.

Role

Description

Permissions

Endpoints
Author

Protect, open, and add policies to Keyavi-protected data. View limited log details.

payload.create

payload.open

payload.read

payload.update

users.read

groups.read

logs.read

POST payloads/protect-remote

POST payloads/protect-local

GET payloads/{payloadId}

POST payloads/{payloadId}/{policy_type}

GET users

GET groups

GET /api/logs/payload

POST payloads/open-remote

POST payloads/open-local
Recipient

Open files with their explicitly granted access level.

payload.open

POST payloads/open-remote

POST payloads/open-local
Security Administrator

Audit logsClosed Detailed records of events and actions taken related to specific payloads such as file access, failed access attempts, file encryption/decryption, and changes. including PII details.

users.read.all

groups.read.all

logs.read.all

GET users

GET users/?expand=true

GET groups

GET /api/logs/payload

GET /api/logs/full-payload

User Administrator

Manage users and groups.

users.read.all

users.write

GET users

GET users/?expand=true

POST users

PATCH users/{user_id}

POST users/{userId}

DELETE users/{userId}/roles/{role_name}

Data Administrator

View and update Keyavi-protected data in the organization.

payload.read.all

payload.update.all

logs.read

users.read

groups.read

GET payloads/{payloadId}

POST payloads/{payloadId}/{policy_type}

GET /api/logs/payload

GET users

GET groups

Policy Administrator

Administers organization-level policies.

 

 

Super Administrator

Can perform all actions. Keyavi manages a single Super Administrator for your organization.

All

All

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

Encrypt can return the following values for result and resultReason.

result

resultReason
AccessGranted

Success

AccessDenied

GeoValidationCountryExclusionFailed

Decrypt

Decrypt can return the following values for result and resultReason.

result

resultReason
AccessGranted

Success

AccessDenied GeoValidationCountryExclusionFailed, TimeEmbargoFailed, UserPayloadNoAccess, or GeoValidationFailed

Audit

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

EncryptionRequest

EncryptionRequest can return the following values for result and resultReason.

result

resultReason
AccessDenied GeoValidationCountryExclusionFailed or GeoValidationFailed