Login

Generates a JSON Web Token (JWT) for the API provided a valid username and password.

important

• The expires_in parameter is used during the login process to specify the duration for which the token will remain valid. The acceptable range for this value is a minimum of 1200 seconds (20 minutes) and a maximum of 157680000 seconds (5 years). If a value below the minimum is provided, it will automatically be set to 1200 seconds (20 minutes). Conversely, if a value exceeds the maximum, it will be limited to 157680000 seconds (5 years).

• Whenever the expires_in parameter is provided, a new token will be generated and any previous one will be automatically invalidated. If the expires_in parameter is not specified, the system will return the existing token if one is available. If no existing token is found, a new token will be created.

(optional) Asymmetric encryption for login

To provide an extra level of security for getting the bearer token it is possible to configure asymetric encryption for login. The type of certificate that needs to be created to use this feature is a Public Key Certificate. This certificate is also known as a Digital Certificate or Identity Certificate. This certificate uses the RSA algorithm for public key cryptography with the OAEP padding scheme and SHA-256 hash function for added security.

To decode the response the user must be in possession of the private key.

If this is the case the service account should be configured with the public key.

In that case the response from login will look like this:

{
    "encrypted": [
        "CoAxwnTyH0xPMQ3lEWEt0x+sFpj7...",
        "xZqYuAj91xpyHhnX/mOoi08nAsJA..."
    ]
}

To decode the payload you have to write a script that iterates over each encrypted string in the encrypted array and calls the decrypt function with each string as an argument using your private key. The decrypted strings should then be concatenated into a single string and parsed as JSON. The JSON should then match the same format as the payload when not using encryption.

Here is an example of code in Nodejs for this process.

const axios = require('axios');
const crypto = require('crypto');
const fs = require('fs');
const main = async () => {
  const payload = {
    username: 'some username',
    password: 'some password',
  };
  const response = await axios.post('/public/api/auth/login', payload);
  const encrypted = response.data.encrypted;
  const decrypted_parts = []
  for(item of encrypted) {
  // decrypting each item in encrypted array
    const decrypted = await decrypt(item);
    decrypted_parts.push(decrypted);
  }
  const decrypted = decrypted_parts.join('');
  const data = JSON.parse(decrypted);

  console.log(data);
}

const decrypt = async (encrypted) => {
  // loading the private key
  const privateKey = fs.readFileSync('./cert/clientprivate.key', 'utf8');
  if (typeof encrypted === 'string') {
    encrypted = Buffer.from(encrypted, 'base64');
  }
  const decryptedData = crypto.privateDecrypt(
    {
      key: privateKey,
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
      oaepHash: "sha256",
    },
    encrypted
  );
  return  decryptedData.toString();
}
main();

The Public Key has to be shared with YOOBIC’s Customer Implementation Manager during the API implementation phase.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "user_id": "53fb03c6546847fe0d30186b",
  "username": "mycompany+yoobicserviceaccount@mycompany.com",
  "email": "support+mycompany+yoobicserviceaccount@yoobic.com",
  "created_date": "2019-02-10T17:20:11.531Z",
  "updated_date": "2019-02-10T17:20:11.531Z",
  "expires_in": 3600,
  "tenant": "mycompany"
}