Yoobic Security API

openapi: 3.2.0
info:
  title: YOOBIC Public Security API
  version: ''
  description: Welcome to the **YOOBIC Public API** documentation.
servers:
- url: https://<base_url>/
tags:
- name: Security
  description: This endpoint exposes the login method in order to create a valid access token for subsequents call to the API, as well as an endpoint for invalidating the current access token. The latter will have the effect of requiring anyone currently using the existing token to login again in order to get the new one.
paths:
  /public/api/auth/login:
    post:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  user_id:
                    type: string
                  username:
                    type: string
                  email:
                    type: string
                  created_date:
                    type: string
                  updated_date:
                    type: string
                  expires_in:
                    type: number
                  tenant:
                    type: string
                example:
                  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
              examples:
                response:
                  value:
                    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
      summary: Login
      operationId: Login
      description: '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:


        ```json

        {

        "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.


        ```js

        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.'
      tags:
      - Security
  /public/api/auth/invalidate_token:
    post:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  token:
                    type: string
                  user_id:
                    type: string
                  username:
                    type: string
                  tenant:
                    type: string
                example:
                  success: true
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                  user_id: 53fb03c6546847fe0d30186b
                  username: mycompany+yoobicserviceaccount@mycompany.com
                  tenant: mycompany
              examples:
                response:
                  value:
                    success: true
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                    user_id: 53fb03c6546847fe0d30186b
                    username: mycompany+yoobicserviceaccount@mycompany.com
                    tenant: mycompany
      summary: Invalidate Token
      operationId: Invalidate Token
      description: Invalidates the existing JSON Web Token (JWT) for the API provided in the Authorization header.
      tags:
      - Security
      parameters:
      - name: Accept
        in: header
        description: e.g. application/json
        required: false
        example: application/json
        schema:
          type: string
      security:
      - oauth2: []
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /
          tokenUrl: /
          scopes: {}