**Licenses**
======================


**Generate a License**
+++++++++++++++++++++++

.. http:post:: /_config/licenses
  
  **Description** This is used for generating new license.

  **HTTP Method** POST
  
  **Endpoint:** ``/_config/licenses``

  **Request Header** ``Authorization`` `Basic <token>`


  **Request Parameters** 

  Body Parameters



    - ``license_name`` (string, *required*): The name of the license to be created.
    - ``plant_id`` (string, *required*): The ID of the plant against which the license is to be generated.
    - ``site_id`` (string, *required*): The ID of the site against  which the license is to be generated. 
    - ``license_validity`` (string, *required*): License validity in years (y), months (m), or days (d).
    - ``app`` (string, *required*): The name of the application against which the license is to be generated.
    - ``license_quota`` (integer, *required*): The quota of the monitors to be managed.
    - ``license_description`` (string, *optional*): The description of the license like who issued it or who will be using it and so on.

  **Sample Request**

    .. code-block:: sh
      
      
      curl --location 'https://app.4pointx.com/_config/licenses' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Basic <token>' \
        --data '{
            "license_name":"L1",
            "plant_id": "7a45d8sde5-92d2-46a7-92d3-85aa4bd57bba",
            "site_id": "4230adcbawd-f349-4780-bf79-4a8c94a3b13b",
            "license_validity": "1y",
            "app":"EMS",
            "license_quota": 100,
            "license_description": "Description"
            }'
  
  
  **Sample Response**

  Success 

    .. sourcecode:: json

      {
        "id": "96978782-b0ea-49dc-9f87-2edf8ba2f126"
      }
          

  Error 

    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": ""Invalid content type"
        }
      } 

    .. sourcecode:: json

      {
        "error": {
          "status": 401,
          "message": "Unauthorised"
        }
      }  

    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Insufficient inputs"
        }
      }

    .. sourcecode:: json

      {
        "error": {
            "status": 400,
            "message": "Invalid input data type"
        }
      }

    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "License validity is invalid"
        }
      }

    .. sourcecode:: json
      
      {
        "error": {
          "status": 400,
          "message": "Invalid application name"
        }
      }

    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Plant id or Site id not found"
        }
      }

    .. sourcecode:: json

      {
        "error": {
            "status": 409,
            "message": "License name License_ABC_Steel already exists"
        }
      }

**Update License**
++++++++++++++++++++++++

.. http:put:: /_config/licenses/<license_id>
  
    **Description** This endpoint allows you to update the details of a specific license by providing its ID.

    **HTTP Method** PUT
    
    **Endpoint** ``/_config/licenses/<license_id>``

    **Request Header** ``Authorization`` `Basic <token>`

    **Request Parameters**

    Body Parameters
    
      - ``license_name`` (string, *optional*): The updated license name.
      - ``plant_id`` (string, *optional*): The plant id associated with the license.
      - ``site_id`` (string, *optional*): The site id associated with the license.
      - ``license_validity`` (string, *optional*): The validity period of the license.
      - ``app`` (string, *optional*): The name of application linked to the license.
      - ``license_quota`` (integer, *optional*): The updated license quota.
      - ``license_description`` (string, *optional*): The updated license description.
      - ``status`` (string, *optional*): The updated status.

    URL Parameters

      - ``license_id`` (string, *required*): The ID of the license to be updated.


    **Sample Request**

      .. code-block:: sh
      
          curl --location --request PUT 'https://app.4pointx.com/_config/licenses/96978782-b0ea-49dc-9f87-2edf8ba2f126' \
         --header 'Content-Type: application/json' \
         --header 'Authorization: Basic YWRtaW46clpvcGN1S3FVSXFteXJPVUNibDVTZGx4bVQzYU55ZG0=' \
         --data '
            {
            "license_name":"L1",
            "plant_id": "7a45d8sde5-92d2-46a7-92d3-85aa4bd57bba",
            "site_id": "4230adcbawd-f349-4780-bf79-4a8c94a3b13b",
            "license_validity": "1y",
            "app":"EMS",
            "license_quota": 100,
            "license_description": "Description",
            "status": "Invalid"
            }'

    **Sample Response**

    Success

      .. sourcecode:: json
                      
         "License updated"     


    Error

      .. sourcecode:: json

        {
          "error":{
            "status": 400,
            "message": "Invalid content type"
            }
        } 

      .. sourcecode:: json

        {
          "error":{
            "status": 401,
            "message": "Unauthorised"
            }
        }

      .. sourcecode:: json

        {
          "error":{
            "status": 400,
            "message":  "Insufficient inputs"
            }
        }

      .. sourcecode:: json

        {
          "error":{
            "status": 400,
            "message": "Invalid license"
            }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "License quota must be a positive integer"
            }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "License name L2 already exists"
            }
        }

      .. sourcecode:: json

        {
            "error": {
            "status": 400,
            "message": "Cannot change status from 'Invalid' to any other value"
            }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Status cannot be empty"
            }
        }


**Get License**
+++++++++++++++++++++++

.. http:get:: /_config/licenses/<license_id>

    
    **Description** This endpoint allows you to retrieve details about a specific license by providing its license_id.



    **HTTP Method** GET


    **Endpoint** ``/_config/licenses/<license_id>``

    **Request Header** ``Authorization`` `Basic <token>`

    **Request Parameters**
      
    URL Parameters

      - ``license_id`` (string, *required*): The license id of the license to be retrieved.
    

    **Sample Request**

      .. code-block:: sh

         curl --location 'https://app.4pointx.com/_config/licenses/96978782-b0ea-49dc-9f87-2edf8ba2f126' \
         --header 'Authorization: Basic <token>'

    **Sample Response**

    Success 

      .. sourcecode:: json
            
        {
            "license_id": "a481bd3e-1d72-4df3-8556-425d7d988cc4",
            "license_key": "%L!YKUjAyB48$mAR{Yo<=7=$WNgLn3}t",
            "license_name": "License_abc1",
            "plant_id": "2424f1ff-57f7-429a-a330-0d730e942d8e",
            "site_id": "2bf0396a-bbc9-4eee-8775-4d928f1ea3f8",
            "created_at": 1742299610,
            "activated_at": 1742316312,
            "license_validity": "1d",
            "expiry_date": 1742402712,
            "app": "EMS",
            "license_quota": 10,
            "status": "Active",
            "license_description": "",
            "latest": true,
            "site_name": "TestSite",
            "plant_name": "PlantTest",
            "license_used": 2
        }

    Error 

      .. sourcecode:: json

        {
          "error": {
            "status": 405,
            "message": "Method not allowed"
          }
        }
        

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Data not found"
          }
        }


      .. sourcecode:: json

        {
          "error": {
            "status": 401,
            "message": "Unauthorised"
          }
        }


**Fetch List of Licenses**
+++++++++++++++++++++++++++++
.. http:GET:: /_config/licenses/_list

    **Description** This endpoint allows you to retrieve a list of all licenses under given site and plant id.

    **HTTP Method** GET

    **Endpoint** ``/_config/licenses/_list``

    **Request Header** ``Authorization`` `Basic <token>`

    **Request Parameters**

    Query Parameters


      - ``site_id`` (string, *required*): The ID of the site for which you want to list licenses.
      - ``plant_id`` (string, *required*): The ID of the plant for which you want to list licenses.

    **Sample Request**

      .. code-block:: sh
        
         curl --location ' https://app.4pointx.com/_config/licenses/_list?site_id=3c6ebc96-c2bf-423d-942c-6c937007c00b&plant_id=edcafba2-8d51-47b6-b1a3-07c12b927a51' \
         --header 'Authorization: Basic <token>' \
         --data ''

    **Sample Response**

    Success 

      .. sourcecode:: json
          
      [
              {
              "app": "CBM",
              "plant_id": "c350f59a-bde2-48e8-af20-0020acc5965b",
              "license_quota": 99,
              "expiry_date": 1741864957,
              "license_validity": "1d",
              "created_at": 1741778413,
              "license_key": "jXQ7Y/6KAE?wG&0CGyu<+18B@IB3u9ra",
              "license_description": "",
              "activated_at": 1741778557,
              "license_name": "test_notification",
              "license_id": "5d1787ad-bc0f-47e3-b329-560578eb0f62",
              "site_id": "b5f359d1-e335-4e60-a9f7-1d375cf81752",
              "status": "Active",
              "latest": true,
              "license_used": 4
          },
          {
              "app": "EMS",
              "plant_id": "c350f59a-bde2-48e8-af20-0020acc5965b",
              "license_quota": 100,
              "expiry_date": 1741863984,
              "license_validity": "1d",
              "created_at": 1740409006,
              "license_key": "R&Rvq66y9+HX8p1a}(+{XOdLn{}aFO?d",
              "license_description": "",
              "activated_at": 1741777584,
              "license_name": "test_renew_msg",
              "license_id": "7b2d3fe5-d1d1-4396-8ce5-10ee2da987bb",
              "site_id": "b5f359d1-e335-4e60-a9f7-1d375cf81752",
              "status": "Active",
              "latest": true,
              "license_used": 11
          },
          {
              "app": "CBM",
              "plant_id": "c350f59a-bde2-48e8-af20-0020acc5965b",
              "license_quota": 100,
              "expiry_date": 1831941443,
              "license_validity": "3y",
              "created_at": 1737331897,
              "license_key": "ePv5B{S7VdvRJPYs&$uBYz+q<vlq1tn3",
              "license_description": "ABC Steel Company CBM CRM plant License 1",
              "activated_at": 1737333443,
              "license_name": "ABC_CRM_CBM_L1",
              "license_id": "7fa8e52b-8c67-42af-b065-f8574b6f5a88",
              "site_id": "b5f359d1-e335-4e60-a9f7-1d375cf81752",
              "status": "Invalid",
              "latest": false,
              "license_used": 0
          }
      ]

    
    Error 

      .. sourcecode:: json
        
        {
          "error": {
            "status": 401,
            "message":  "Unauthorised"
          }
        }

      .. sourcecode:: json
        
        {
          "error": {
            "status": 400,
            "message":  "Insufficient inputs"
          }
        }   

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Data not found"
          }
        }     

            
**Activate Licenses**
+++++++++++++++++++++++++++++
.. http:PUT:: /_config/licenses/_activate

    **Description** This endpoint allows you to activate a new license. It also deactivates an existing license before activating a new license if required.

    **HTTP Method** PUT

    **Endpoint** ``/_config/licenses/_activate``

    **Request Header** ``Authorization`` `Basic <token>`

    **Request Parameters**

    Body Parameters


      - ``license_key`` (string, *required*): The license key of the license to be activated.
      - ``deactivate`` (string, *optional*): The user can proceed to deactivate an existing license and then activate the new one if this parameter is passed along with license_key with "yes" as its value.

    **Sample Request**

      - **Case 1: Passing only license_key**

      ..  code-block:: sh
        
        curl --location 'https://app.4pointx.com/_config/licenses/_activate' \
        --header 'Authorization: Basic <token>' \
        --data '{
            "license_key": "9[uY@]WT@zvoasdas?NweOZSBr2A8*ELr%t%"
        }'   

      - **Case 2: Passing license_key along with deactivate="yes"**

      .. code-block:: sh
        
        curl --location 'https://app.4pointx.com/_config/licenses/_activate' \
        --header 'Authorization: Basic <token>' \
        --data '{
            "license_key": "9[uY@]WT@zvoasdas?NweOZSBr2A8*ELr%t%",
            "deactivate": "yes"
        }'

    **Sample Response**

    Success

      .. sourcecode:: json

        "License activated successfully"


    Error

      .. sourcecode:: json


        {
          "error":{
            "status": 400,
            "message":  "Insufficient inputs"
            }
        }


      .. sourcecode:: json

        {
          "error":{
            "status": 401,
            "message": "Unauthorised"
            }
        }


      .. sourcecode:: json

        {
          "error":{
            "status": 400,
            "message": "License does not exist"
            }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Invalid license data:Required fields cannot be empty"
            }
        }

      .. sourcecode:: json

        {
          "error":{
            "status": 400,
            "message": "License either in-use/expired/revoked"
            }
        }


      .. sourcecode:: json

        {
          "error":{
            "status": 500,
            "message": "License activation failed"
            }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 409,
            "message": "Unable to activate the license as the current monitor count (11) exceeds the permitted count (10)"
            }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 202,
            "message": {
              "app_name": "CBM",
              "current_license": {
                  "name": "ABC Steel Company_HSM_CBM_L1",
                  "quota": 100,
                  "expiry_date": "20/01/2026"
              },
              "new_license": {
                  "name": "ABC Steel Company_HSM_CBM_L3",
                  "quota": 100,
                  "expiry_date": "18/03/2026"
              }
            }
          }
        }


**Get Notification**
+++++++++++++++++++++++

.. http:get:: /_config/licenses/_notification

    **Description** This endpoint allows user to be notified if a license is about to expire.

    **HTTP Method** GET

    **Endpoint** ``/_config/licenses/_notification``

    **Request Header** ``Authorization`` `Basic <token>`

    Query Parameters


      - ``site_id`` (string, *optional*): The ID of the site for which you want to trigger Notification.
      - ``plant_id`` (string, *optional*): The ID of the plant for which you want to trigger Notification.
      - ``app`` (string, *optional*): The name of app for which you want to trigger Notification.

    .. note::
        -   Parameter "app" currently takes values CBM,EMS and LM(License Management) to trigger individual app notification and notification for all in case of LM.

    **Sample Request**


      - **Case 1: No input parameters**
      ..  code-block:: sh
            
         curl --location 'https://app.4pointx.com/_config/_notification/' \
         --header 'Authorization: Basic <token>'
              
      - **Case 2: With input parameters site_id,plant_id and app**
      ..  code-block:: sh
            
         curl --location 'https://app.4pointx.com/site_id=3c6ebc96-c2bf-423d-942c-6c937007c00b&plant_id=edcafba2-8d51-47b6-b1a3-07c12b927a51&app=CBM' \
         --header 'Authorization: Basic <token>'

    **Sample Response**

    Success 

      - **Case 1: No input parameters**
      .. sourcecode:: json

        {
          "notification": ""
        }

      .. sourcecode:: json

        {
          "notification": "The EMS license for PlantTest plant is about to expire"
        }
     
      .. sourcecode:: json

        {
          "notification": "The CBM license for PlantTest plant is about to expire"

        }

      .. sourcecode:: json

        {
          "notification": [
              "The CBM license for PlantTest plant is about to expire",
              "The EMS license for PlantTest plant is about to expire"
          ]
        }

      - **Case 2: With input parameters site_id,plant_id and app**

        {
          "notification": [],
          "site_id": "2bf0396a-bbc9-4eee-8775-4d928f1ea3f8",
          "plant_id": "2424f1ff-57f7-429a-a330-0d730e942d8e",
          "app": "LM"
        }

      .. sourcecode:: json

        {
          "notification": [
              "The CBM license has expired on Feb 21 2025. Please contact your Administrator to renew your license.",
              "The EMS license has expired on Feb 21 2025. Please contact your Administrator to renew your license.",
              "The EMS license is about to expire on Mar 19 2025. Please contact your Administrator to renew your license."
          ],
          "site_id": "2bf0396a-bbc9-4eee-8775-4d928f1ea3f8",
          "plant_id": "2424f1ff-57f7-429a-a330-0d730e942d8e",
          "app": "LM"
        }

      .. sourcecode:: json

        {
          "notification": [
              "The EMS license has expired on Feb 21 2025. Please contact your Administrator to renew your license.",
              "The EMS license is about to expire on Mar 19 2025. Please contact your Administrator to renew your license."
          ],
          "site_id": "2bf0396a-bbc9-4eee-8775-4d928f1ea3f8",
          "plant_id": "2424f1ff-57f7-429a-a330-0d730e942d8e",
          "app": "EMS"
        }

      .. sourcecode:: json
        {
          "notification": [
              "The CBM license has expired on Feb 21 2025. Please contact your Administrator to renew your license."
          ],
          "site_id": "2bf0396a-bbc9-4eee-8775-4d928f1ea3f8",
          "plant_id": "2424f1ff-57f7-429a-a330-0d730e942d8e",
          "app": "CBM"
        }
  
    Error 

      .. sourcecode:: json

        {
          "error": {
            "status": 401,
            "message": "Unauthorised"
            }
        }
      
      .. sourcecode:: json

        {
          "error": {
          "status": 403,
          "message": "Admin user"
          }
        }
        



**Verify App Access**
+++++++++++++++++++++++

.. http:get:: /_config/licenses/_verify

    **Description** This endpoint is used to Verify App Access.

    **HTTP Method** GET

    **Endpoint** ``/_config/licenses/_verify``

    **Request Header** ``Authorization`` `Basic <token>`

    **Request Parameters**

    Query Parameters


      - ``app`` (string, *required*): The name of app for which you want to verify user access(e.g., "CBM," "EMS," or "LM").


    .. note::
      -   This API is strictly internal, operating within the confines of the VM, and are inaccessible to any user/external parties.

    **Sample Request**

      .. code-block:: sh

         curl --location 'https://app.4pointx.com/_config/licenses/_verify?app=LM' \
         --header 'Authorization: Basic <token>'

    **Sample Response**

    Success 

      .. sourcecode:: json

        {
            "Authorised"
        }
      
      .. sourcecode:: json

        {
            "Admin user"
        }

  
    Error 

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "App not given"
          }
        }

      .. sourcecode:: json

        {
          "error": {
            "status": 401,
            "message": "Unauthorised"
          }
        }