Using service account creds to access the DotAlign API

Updated by Jaspreet Bakshi

Your DotAlign deployment is API first, that is, any function or data visible to you in the DotAlign app is also accessible via a rich API. If you'd like to access your DotAlign API, you need to be able to authenticate to it first. The following steps describe how you can authenticate to the API using Azure Active Directory.

  1. Create an app registration inside Azure. The instructions are here. We call this the secondary app registration, as it works in conjunction with your primary DotAlign app registration that was created at the time of deployment, to provide access to the DotAlign API.
  2. Once you have created the app registration, collect the following items of information, which will be needed to get the access token. Below the properties are shown with sample values:
// The GUID Id of your Azure tenant
TENANT_ID="eb032b2d-8f5e-47da-a44a-7a6dbe8a1b8e"
 
// The GUID id of the app registration made by you, which includes the DotAlignCloud.Read.All permission. We also refer to this as the “secondary” app registration.
CLIENT_ID="0bffe3eb-2031-4629-8236-5a8be87c636c"
 
// Secret generated inside the secondary app registration
CLIENT_SECRET=73a0ccbfadb8dQsVoHqD-jBhd251VXwFsI
 
// The GUID id of the app registration generated by the DotAlign deployment script, also referred to as the “primary” app registration, followed by the string “/.default”
SCOPE="7c8a7fed-d251-4057-b50b-73a0ccbfadb8/.default"
 
// This value should be “client_credentials” as that is the OAuth method being used
GRANT_TYPE="client_credentials"
  1. The inputs from above are used to get an access token, using code like the following. The inputs are placed inside an “environment” object, and made available to the method.
async function getAccessToken(environment) {
    var authEndpoint = `https://login.microsoftonline.com/${environment.tenant_id}/oauth2/v2.0/token`;

    var body = `grant_type=${environment.grant_type}&client_id=${environment.client_id}&client_secret=${environment.client_secret}&tenant_id=${environment.tenant_id}&scope=${environment.scope}`;

    var args = {
        method: "POST",
        body: body,
        headers: {
            "Content-Type": "application/x-www-form-urlencoded",
        }
    };

    const response = await fetch(authEndpoint, args);
    return response.json();
}

  1. And once you have the access token, you can get data from specific endpoints using code like the following:
async function getData(url, accessToken) { 
    var args = {
        method: "GET",
        headers: {
            Authorization: "Bearer " + accessToken,
        }
    };

    const response = await fetch(url, args);
    return response.json();
}

If you run into any issues, please reach out to [email protected].

How Did We Do?