Authentication

Authentication

Authentication is the first step of programmatically obtaining an JSON Web Token to use with the API.

If the latest Terms of Use (ToU) for LMC has not been accepted by the user, the authentication request will fail with a status of 400.

• Endpoint: /cloud-service-auth/userlogin
• Method: POST
• Body:

{
    "name": "<email address>",      // your email address
    "password": "<password>",       // password for logging into LMC
    /* The termsOfUse can be omitted if the terms of use has been accepted by the user. */
    "termsOfUse":[{
        "name":"general",
        /* ToU document version in YYYY-MM-DD format, for example 2020-11-10 */
        "acceptance":"<date>"       
    }]
}

Hint: Everytime a new version of the Terms Of Use document is released by LMC, the user logging in should accept it before a stipulated time. In such cases, it is recommended to manually login to LMC and accept the ToU before using the APIs.

JavaScript (NodeJS) Example

const getInitialToken = () => {
    const headers = new fetch.Headers({
        "Content-Type": "application/json;charset=UTF-8"
    });

    return fetch(config.baseurl + "/cloud-service-auth/userlogin", {
        method: "POST",
        headers: headers,
        body: JSON.stringify({
            "name": "<email address>",
            "password": "<password>"
        })
    }).then(resp => resp.json());
};

Two-Factor Authentication (2FA)

2FA (or MFA - Multi Factor Authentication) is introduced on https://en.wikipedia.org/wiki/Multi-factor_authentication as follows:

Multi-factor authentication (MFA; two-factor authentication, or 2FA, along with similar terms) is an electronic authentication method in which a user is granted access to a website or application only after successfully presenting two or more pieces of evidence (or factors) to an authentication mechanism.

LMC uses standard TOTP method to validate the 2FA code.

More information about this can be found in https://en.wikipedia.org/wiki/Time-based_one-time_password

Enable 2FA in LMC

After logging into the LMC UI, 2FA can be enabled for a user in the user profile by clicking on the Activate two-factor authentication link. Follow the instructions provided in the dialog to enable 2FA.

After 2FA has been enabled for the user, the correct 2FA code needs to be a part of the authentication request.

• Endpoint: /cloud-service-auth/userlogin
• Method: POST
• Body:

{
    "name": "<email address>",      // your email address
    "password": "<password>",       // password for logging into LMC
    "code": "6 digit 2FA code",     // code is mandatory if 2FA is enabled for the user
}

Authorization

With the resulting token from the Authentication request, we can now upgrade this token to obtain a token with a context, to be used with further API requests.

• Endpoint: /cloud-service-auth/auth
• Method: POST
• Body:

{
    accountIds: [ /* list of account UUIDs */ ]
}

JavaScript (NodeJS) Example

 const upgradeToken = (initialToken, ids) => {
     if (!initialToken.value) {
         throw new Error("Missing JWT");
     }

     const headers = new fetch.Headers({
         "Content-Type": "application/json;charset=UTF-8",
         "Authorization": "Bearer " + initialToken.value
     });

     return fetch(config.baseurl + "/cloud-service-auth/auth", {
         method: "POST",
         headers: headers,
         body: JSON.stringify({
             accountIds: ids
         })
     }).then(resp => {
         if (resp.ok) {
             // do something with the token here
         } else {
             console.log(resp);
             throw new Error("Error upgrading JWT");
         }
     });
 };