``/v2/users``
--------------

.. tabularcolumns:: |p{1.5cm}|p{5cm}|p{8.5cm}|

+--------+--------------------------+----------------------+
| Method | URL                      | Description          |
+========+==========================+======================+
| GET    | ``/v2/users``            | Retrieves current    |
|        |                          | list of all users.   |
+--------+--------------------------+----------------------+
| POST   | ``/v2/users``            | Adds a new user.     |
+--------+--------------------------+----------------------+
| PUT    | ``/v2/users``            | Modifies an existing |
|        |                          | user.                |
+--------+--------------------------+----------------------+
| PUT    | ``/v2/users/deactivate`` | Deactivate an        |
|        |                          | existing user.       |
+--------+--------------------------+----------------------+
| PUT    | ``/v2/users/reactivate`` | Reactivate an        |
|        |                          | existing user.       |
+--------+--------------------------+----------------------+
| DELETE | ``/v2/users``            | Deletes an existing  |
|        |                          | user.                |
+--------+--------------------------+----------------------+

Header (required)
......................

``x-lxt-api-token``: "token from login"

GET
............

``/v2/users``

* Example 1: Get All Users

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -X GET https://<IP or FQDN>/api/v2/users
          
  Output (formatted):

  ::

     {
      "status":200,
      "message":"Success",
      "data":[
        {
          "email":"tset",
          "id":"IPM0N3CRFDHM4GQK15319464799176RQ299QFIJBA8B",
          "userId":"test",
          "firstName":"Bob",
          "lastName":"Smith",
          "status":"active",
          "customerId":null
        },
        {
          "email":"test",
          "id":"RUKTJDOYFSGJ4JO11532442929347PUPJAMFGP8TYE6",
          "userId":"loc",
          "firstName":"",
          "lastName":"",
          "status":"active",
          "customerId":null
        }
      ]
    }

  RESP_CODE: ``200``

* Example 2: Get Users with query parameter ``email``

  Command:


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -X GET https://<IP or FQDN>/api/v2/users?email=tset
          
  Output (formatted):

  ::

     {

       "status":200,
       "message":"Success",
       "data":[{"email":"tset",
                "id":"IPM0N3CRFDHM4GQK15319464799176RQ299QFIJBA8B",
                "userId":"test",
                "firstName":"Bob",
                "lastName":"Smith",
                "status":"active",
                "customerId":null
               }]
     }

  RESP_CODE: ``200``

* Example 3: Get Users with query parameter ``userId``

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -X GET https://<IP or FQDN>/api/v2/users?userId=loc
          

  Output (formatted):

  ::

      {"status":200,
       "message":"Success",
       "data":[{"email":"test",
                "id":"RUKTJDOYFSGJ4JO11532442929347PUPJAMFGP8TYE6",
                "userId":"loc",
                "firstName":"",
                "lastName":"",
                "status":"active",
                "customerId":null}]
      }

  RESP_CODE: ``200``

* Example 4: Get Users with an invalid email

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -X GET https://<IP or FQDN>/api/v2/users?email=invalid@email.com

  Output (formatted):

  ::

     {
      "status":400,
      "message":"User(s) not found.",
      "data":[]
     }

  RESP_CODE: ``400``

POST
......

Use POST to add a new user. An error will be returned if this user
already exists in the system.

``/v2/users``

* Example Input JSON

  The following JSON should be used when adding a new user to the system.
  POST parameters should be in JSON only.

  ``v2users.add.user1``

  ::

     {
      "userId":"testuser1", (required)
      "password":"password1", (optional)
      "email":"testuser1@test.com", (required)
      "firstName":"TFirst", (optional)
      "lastName":"TLast", (optional)
      "customerId":"1234", (optional)
      "customerName":"", (optional, recommended if customerId is provided)
      "roles":[ (optional)
               {
                "name":"layerx_role1", (optional)
                "product":"Global SIP"(optional)
               }]
     }

  * ``customerName``
   
    The API will automatically create a customer for the user
    if ``customerName`` is provided. The ``customerName`` will be returned with each
    subsequent API GET request. The ``customerName`` should be unique. New customers
    can be seen in the user interface under the **Access Controls-> Customer** area.
    The admin user can then add, modify, or delete
    resource filters to control what data this user can see.
  
  * ``customerId``
  
    The API also supports the use of a ``customerId``. The ``customerId`` is usually a
    customer specific unique identifier that has meaning to the end user.
    If ``customerId`` is provided, the API will use the ``customerId`` as the
    determining factor on whether or not to create a new customer. The API
    will automatically create a new customer for the user if ``customerId`` does
    not already exist in the system. 
    
    .. note::
    
       ``customerName`` is still an optional field. The system still needs something
       user friendly to display to the end user in the user interface.
    
       ``customerId`` is usually not very meaningful or useful to the end user. 
       It is recommended that the ``customerName`` is also used in conjuntion
       with ``customerId`` to provide a user friendly customer name.

* POST High Level (No customer information)

  The following flow demonstrates the system behavior
  when ``customerId`` and ``customerName`` are not provided.
  
  |VAA-dashboard-API-high-level-no-cust-info|

* POST High Level (with customer information)

  The following flow demonstrates the system behavior
  when ``customerId`` and ``customerName`` are provided.
  
  |VAA-dashboard-API-high-level-with-cust-info|
  
* Example 1: Add new user

  Command:


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.add.user1
          -X POST https://<IP or FQDN>/api/v2/users


  or


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d '{"userId":"testuser1",
               "password":"password1",
               "email":"testuser1@test.com",
               "firstName":"TFisrt",
               "lastName":"TLast",
               "roles": [{"name":"layerx_role1",
                          "product":"Global SIP"}]
              }'
          -X POST https://<IP or FQDN>/api/v2/users


  Output (formatted):

  ::

     {"status":200,
      "message":"Success",
      "data":[{"email":"testuser1@test.com",
               "id":"4e37d6c336d2adbf52bbc5dda8[...]",
               "userId":"testuser1",
               "firstName":"TFirst",
               "lastName":"TLast",
               "status":"active",
               "customerId":null }]
     }  

  RESP_CODE: ``200``

* Example 2: Add an existing user

  Command:


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.add.user1
          -X POST https://<IP or FQDN>/api/v2/users


  Output (formatted):
  
  ::

     {"status":400,
      "message":"User already exists.",
      "data":[]
     }

  RESP_CODE: ``400``


PUT
......

Use PUT to modify an existing user. An error will be returned if the
user does not exist in the system.

::

  /v2/users
  /v2/users/deactivate
  /v2/users/reactivate

* Example Input JSON

  The following JSON should be used when modifying a new user to the
  system. PUT parameters should be in JSON only.

  ``v2users.modify.user1``

  ::

     {"id":"xxxxxxxxxxxxxxxxx", (optional)
      "userId":"testuser1", (required)
      "password":"password1", (optional)
      "email":"testuser1@test.com", (required)
      "firstName":"Firstname Changed", (optional)
      "lastName":"Last Name changed", (optional)
      "customerId":"1234", (optional)
      "customerName":"Customer B", (optional, recommended if customerId is provided)
      "roles":[ (optional)
         {"name":"layerx_role1", (optional)
          "product":"Global SIP"(optional)
         }]
     }

* ``customerName`` and ``customerId``

  Please refer to POST section for ``customerName`` and ``customerId`` parameters.

* Example 1: Update existing user

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.modify.user1
          -X PUT https://<IP or FQDN>/api/v2/users

  or

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d '{"id":"xxxxxxxxxxxxxxxxx",
               "userId":"testuser1",
               "password":"password1",
               "email":"testuser1@Changed",
               "lastName":"Last Name changed",
               "customerId":"1234",
               "roles":[{"name":"layerx_role1",
                         "product":"Global SIP"}]}'
         -X PUT https://<IP or FQDN>/api/v2/users

  Output (formatted):

  ::

     {"status":201,
      "message":"Success",
      "data":{"email":"testuser1@test.com",
             "id":"4e37d6c336d2adbf52bbc5d[...]",
             "userId":"testuser1",
             "firstName":"Firstname Changed",
             "lastName":"Last Name changed",
             "status":"active",
             "customerId":"1234" }
     }
     

  RESP_CODE: ``200``

* Example 2: Deactivate user

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.modify.user1
          -X PUT https://<IP or FQDN>/api/v2/users/deactivate

  or


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d '{"id":"xxxxxxxxxxxxxxxxx",
               "userId":"testuser1",
               "password":"password1",
               "email":"testuser1@Changed",
               "lastName":"Last Name changed",
               "customerId":"1234",
               "roles":[{"name":"layerx_role1",
                          "product":"Global SIP"}]}'
         -X PUT https://<IP or FQDN>/api/v2/users/deactivate


  Output (formatted):

  ::

     {"status":201,
      "message":"Success",
      "data":{"email":"testuser1@test.com",
              "id":"4e37d6c336d2adbf52bb[...]",
              "userId":"testuser1",
              "firstName":"Firstname Changed",
              "lastName":"Last Name changed",
              "status":"inactive",
              "customerId":"1234"}
     }

  RESP_CODE: ``200``

* Example 2: Reactivate user

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.modify.user1
          -X PUT https://<IP or FQDN>/api/v2/users/reactivate

  or


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d '{"id":"xxxxxxxxxxxxxxxxx",
               "userId":"testuser1",
               "password":"password1",
               "email":"testuser1@Changed",
               "lastName":"Last Name changed",
               "customerId":"1234",
               "roles":[{"name":"layerx_role1",
                          "product":"Global SIP"}]}'
         -X PUT https://<IP or FQDN>/api/v2/users/reactivate

  Output (formatted):

  ::

    {"status":201,
     "message":"Success",
     "data":{"email":"testuser1@test.com",
             "id":"4e37d6c336d2adbf52bbc[...]",
             "userId":"testuser1",
             "firstName":"Firstname Changed",
             "lastName":"Last Name changed",
             "status":"active",
             "customerId":"1234"}
    }

  RESP_CODE: ``200``

DELETE
..........

Use DELETE to delete a user from the system.

``/v2/users``

* Example Input JSON

  See POST and PUT section for example JSON. DELETE parameters should be
  in JSON only.

* Example 1: Delete existing user

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.add.user1
          -X DELETE https://<IP or FQDN>/api/v2/users

  or


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d '{"id":"xxxxxxxxxxxxxxxxx",
               "userId":"testuser1",
               "password":"password1",
               "email":"testuser1@Changed",
               "lastName":"Last Name changed",
               "customerId":"1234",
               "roles":[{"name":"layerx_role1",
                         "product":"Global SIP"}]}'
          -X DELETE https://<IP or FQDN>/api/v2/users

  Output (formatted):

  ::

     {"status":201,
      "message":"Success",
      "data":[]
     }

  RESP_CODE: ``200``

* Example 2: Delete existing user again

  Command:

  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d@test_data/v2users.add.user1
          -X DELETE https://<IP or FQDN>/api/v2/users

  or


  ::

     curl -s 
          -H x-lxt-api-token:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9[...]
          --insecure 
          -w "RESP_CODE: %{response_code}" 
          -d '{"id":"xxxxxxxxxxxxxxxxx",
               "userId":"testuser1",
               "password":"password1",
               "email":"testuser1@Changed",
               "lastName":"Last Name changed",
               "customerId":"1234",
               "roles":[{"name":"layerx_role1",
                         "product":"Global SIP"}]}'
          -X DELETE https://<IP or FQDN>/api/v2/users

  Output (formatted):

  ::

     {"status":404,
      "message":"Invalid user",
      "data":[]
     }

  RESP_CODE: ``404``

.. |VAA-dashboard-API-high-level-no-cust-info| image:: /src/images/VAA-dashboard-API-high-level-no-cust-info.png
.. |VAA-dashboard-API-high-level-with-cust-info| image:: /src/images/VAA-dashboard-API-high-level-with-cust-info.png