Tenant API

The Worklytics Tenant API allows your organization (as Worklytics Tenant) to automate tasks such as the creation and management of data connections.

Please be advised that the Tenant API is currently available as a BETA feature.

Introduction

Currently, the main use case for the Tenant API is to create and manage data connections when using the Worklytics Pseudonymization Proxy.

After setting up a Proxy instance in the cloud provider of your choice, the last step of the configuration is to create a data connection in the Worklytics Web App. Once the connection is ready, Worklytics will start to process data from the data sources you've configured.

That last configuration step could be simplified by making HTTP calls in a RESTful manner to the Tenant API using the configuration values of your Proxy instances.

Authentication

The authentication depends on the cloud provider where you've deployed the Proxy instance, but all Tenant API calls must include:

An Authorization header with a valid JWT ID Token that Worklytics can verify against its issuer (being either AWS or GCP).
- That token must include the identifier (typically the email) of the user of your organization that has been granted with the DataConnectionAdmin role in the Worklytics platform. See the access control documentation for more details.
- The aud claim of the token must include https://app.worklytics.co.
A x-worklytics-tenant-id header that identifies your organization as Worklytics tenant. This is your tenant's Service Account Unique ID that is also required to set up the Proxy instance (available here).

Below we describe how to obtain the JWT ID Token depending on the cloud provider of your choice.

Google Cloud Platform (GCP)

If you're using GCP as your cloud provider, we assume that you have installed the gCloud CLI tool which is a pre-requisite of the Worklytics Proxy configuration.

The recommended way to obtain the JWT ID Token is to use the following command:

gcloud auth print-identity-token \
  --impersonate-service-account="my-account@example.iam.gserviceaccount.com" \
  --include-email \
  --audiences="https://app.worklytics.co"

Using a Service Account (SA) is the recommended way; so, the user running the command must be able to impersonate that SA (my-account@example.iam.gserviceaccount.com in the example). You could also directly use the SA as gcloud principal to get the ID Token (in that case, the --include-email flag is not needed). Check the auth print-identity-token command documentation for more details.

We provide a set of GCP Terraform modules to assist you with creating the Service Account for this use case. These modules also include examples that generate shell scripts to run Tenant API calls for your connections.

In any case, make sure the token includes the email of the user that has been granted the DataConnectionAdmin role.

Amazon Web Services (AWS)

If you're using AWS as your cloud provider, we assume that you have installed the AWS CLI tool which is a pre-requisite of the Worklytics Proxy configuration.

The recommended way to obtain the JWT ID Token is to use the following command:

aws cognito-identity get-open-id-token-for-developer-identity \
 --identity-pool-id "your-identity-pool-id" \
 --logins app.worklytics.co="john@acme.com" \
 --region "us-east-1"

In this case, the get-open-id-token-for-developer-identity option requires an Amazon Cognito Identity Pool. We provide a set of AWS Terraform modules to assist you with creating the Identity Pool for this use case. These modules also include examples that generate shell scripts to run Tenant API calls for your connections.

Notice that john@acme.com in the example, is the email of the user that has been granted the DataConnectionAdmin role.

Data Connections

Endpoints description:

GET /tenant/data-connections/:id
POST /tenant/data-connections
PUT /tenant/data-connections/:id
DELETE /tenant/data-connections/:id

All endpoints consume and produce JSON objects, and they will return common HTTP status codes:

200: The request was successful.
403: The user is not authorized to perform the operation.
404: The resource was not found.
400: The request (data connection object) was malformed or invalid.

The Data Connection object

The following JSON object represents a data connection with ID 4818059952914432 which connects a Proxy instance deployed in AWS (a lambda function) that has configured Google Workspace as data source (integrationId field).

{
  "id": 4818059952914432,
  "integrationId": "gdirectory-psoxy",
  "settings": {
    "PROXY_DEPLOYMENT_KIND": "AWS",
    "PROXY_ENDPOINT": "https://qnkhne90n8.execute-api.us-east-1.amazonaws.com/live/psoxy-gdirectory/",
    "PROXY_AWS_REGION": "us-east-1",
    "PROXY_AWS_ROLE_ARN": "arn:aws:iam::405366049093:role/psoxyCaller",
    "ADMIN_TO_IMPERSONATE": "john@acme.com"
  }
}

The minimum required fields for a connection are defined in the settings object:

PROXY_DEPLOYMENT_KIND: The cloud provider where the Proxy instance is deployed. It could be either AWS or GCP.
PROXY_ENDPOINT: The URL of the Proxy instance (for API connectors only).
PROXY_BUCKET: The name of the bucket where the Proxy will store sanitized data (for Bulk File connectors only).
PROXY_AWS_REGION: The AWS region where the Proxy instance is deployed. This field is only required if PROXY_DEPLOYMENT_KIND is AWS.
PROXY_AWS_ROLE_ARN: The ARN of the IAM role that the Proxy instance assumes to access the data source. This field is only required if PROXY_DEPLOYMENT_KIND is AWS.

There are other attributes that may vary depending on the data source you want to connect to. Some of them are required, for example: GITHUB_ORGANIZATION for GitHub data sources. Others are optional, like ADMIN_TO_IMPERSONATE in the example above (it's only required for Google Workspace data sources).

The Proxy project will help you to complete all the required fields for each data connection, and our AWS Terraform modules contain all the necessary tools to automate the Tenant API calls.

Tenant API responses could include additional attributes in the data connection object, such as the creation date, last update date, etc. These fields can be ignored when creating or managing data connections. Besides the settings object field, only the integrationId attribute and the id attribute (for existing connections) are required.

Below, there are example calls for all the endpoints.

Create a Data Connection

AWS

curl -X POST https://intl.worklytics.co/tenant-api/data-connections \
  -H "Authorization: Bearer <your ID Token>" \
  -H "x-worklytics-tenant-id: <your unique tenant ID>"\
  -H "Content-Type: application/json" \
  -d '{
        "integrationId": "<integration-id>",
        "settings": {
          "PROXY_DEPLOYMENT_KIND": "AWS",
          "PROXY_ENDPOINT": "https://acme.execute-api.us-east-1.amazonaws.com/live/integration-id",
          "PROXY_AWS_REGION": "us-east-1",
          "PROXY_AWS_ROLE_ARN": "<role ARN>"
        }
     }'

GCP

curl -X POST https://intl.worklytics.co/tenant-api/data-connections \
  -H "Authorization: Bearer <your ID Token>" \
  -H "x-worklytics-tenant-id: <your unique tenant ID>"\
  -H "Content-Type: application/json" \
  -d '{
        "integrationId": "<integration-id>",
        "settings": {
          "PROXY_DEPLOYMENT_KIND": "GCP",
          "PROXY_ENDPOINT": "https://us-central1-acme.cloudfunctions.net/integration-id",
        }
     }'

Read a Data Connection

AWS and GCP use-cases are the same:

curl -X GET https://intl.worklytics.co/tenant-api/data-connections/<connection-id> \
  -H "Authorization: Bearer <your ID Token>" \
  -H "x-worklytics-tenant-id: <your unique tenant ID>"

Update a Data Connection

AWS

curl -X PUT https://intl.worklytics.co/tenant-api/data-connections/<connection-id> \
  -H "Authorization: Bearer <your ID Token>" \
  -H "x-worklytics-tenant-id: <your unique tenant ID>"\
  -H "Content-Type: application/json" \
  -d '{
        "integrationId": "<integration-id>",
        "settings": {
          "PROXY_DEPLOYMENT_KIND": "AWS",
          "PROXY_ENDPOINT": "https://acme.execute-api.us-east-1.amazonaws.com/live/integration-id",
          "PROXY_AWS_REGION": "us-east-1",
          "PROXY_AWS_ROLE_ARN": "<role ARN>"
        }
     }'

GCP

curl -X PUT https://intl.worklytics.co/tenant-api/data-connections/<connection-id> \
  -H "Authorization: Bearer <your ID Token>" \
  -H "x-worklytics-tenant-id: <your unique tenant ID>"\
  -H "Content-Type: application/json" \
  -d '{
        "integrationId": "<integration-id>",
        "settings": {
          "PROXY_DEPLOYMENT_KIND": "GCP",
          "PROXY_ENDPOINT": "https://us-central1-acme.cloudfunctions.net/integration-id",
        }
     }'

Delete a Data Connection

AWS and GCP use-cases are the same:

curl -X DELETE https://intl.worklytics.co/tenant-api/data-connections/<connection-id> \
  -H "Authorization: Bearer <your ID Token>" \
  -H "x-worklytics-tenant-id: <your unique tenant ID>"

PreviousZoom Sanitized Data

Last updated 12 days ago