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 pseudonimization proxy.
After setting up a Psoxy 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 API using the configuration values of your Psoxy instances.
Authentication
The authentication depends on the cloud provider where you've deployed the Psoxy 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 includehttps://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 Psoxy 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 Psoxy configuration.
The recommended way to obtain the JWT ID Token is to use the following command:
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.
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 Psoxy configuration.
The recommended way to obtain the JWT ID Token is to use the following command:
In this case, the get-open-id-token-for-developer-identity option requires an Amazon Cognito Identity Pool. We provide an AWS Terraform module to help you create the Identity Pool for this use-case.
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:
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 Psoxy instance deployed in AWS (a lambda function) that has configured Google Workspace as data source (integrationId
field).
The minimum required fields for a connection are defined in the settings
object:
PROXY_DEPLOYMENT_KIND
: The cloud provider where the Psoxy instance is deployed. It could be eitherAWS
orGCP
.PROXY_ENDPOINT
: The URL of the Psoxy instance.PROXY_AWS_REGION
: The AWS region where the Psoxy instance is deployed. This field is only required ifPROXY_DEPLOYMENT_KIND
isAWS
.PROXY_AWS_ROLE_ARN
: The ARN of the IAM role that the Psoxy instance assumes to access the data source. This field is only required ifPROXY_DEPLOYMENT_KIND
isAWS
.
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 Psoxy project will help you to complete all the required fields for each data connection, and our AWS Terraform module contains all the necessary tools to automate the Tenant API calls (AWS use-case only).
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 call examples for all the endpoints.
Create a Data Connection
AWS
GCP
Read a Data Connection
AWS and GCP use-cases are the same:
Update a Data Connection
AWS
GCP
Delete a Data Connection
AWS and GCP use-cases are the same:
Last updated