.. role:: green

User Functions
================

Fetch a User
------------

**Type:** :guilabel:`GET`

.. py:function:: https://cloud.syminet.com/api/v1/users/{USERNAME}

    Return details of a user.

**Required URL Parameters:**

USERNAME
  Username to fetch.

.. code-block:: shell
   :caption: Curl

    curl --request GET \
         --url https://cloud.syminet.com/api/v1/users/USERNAME \
         --header "authorization:bearer $API_TOKEN"

.. code-block:: json
    :caption: Response

    {
      "admin": true,
      "email": "user@example.com",
      "id": 2316,
      "last_login": "Wed, 20 Nov 2024 00:05:28 GMT",
      "last_login_ip": "192.168.1.24",
      "username": "mytestuser7"
    }   


.. _List User Permissions:

List User Permissions
---------------------

**Type:** :guilabel:`GET`

.. py:function:: https://cloud.syminet.com/api/v1/users/{USERNAME}/perms

    Return a list of permissions for ``USERNAME``.

**Required URL Parameters:**

USERNAME
  Username to list permissions for.

.. code-block:: shell
   :caption: Curl

    curl --request GET \
         --url https://cloud.syminet.com/api/v1/users/USERNAME/perms \
         --header "authorization:bearer $API_TOKEN"


.. code-block:: json
    :caption: Response

    {
      "admin": false,
      "domains": [],
      "email": "info@syminet.com",
      "firewalls": [],
      "global": {
        "create_domain": false,
        "create_flexip": false,
        "create_fw": false,
        "create_snapshot": false,
        "create_vm": true,
        "create_volume": false,
        "use_api": false
      },
      "id": 2403,
      "slices": [
        {
          "id": 3828,
          "perms": "rw",
          "vmname": "11test1-newvm"
        }
      ],
      "snapshots": [
        {
          "id": 15258,
          "name": "11test1-newvm-1731969462",
          "perms": "ro"
        },
        {
          "id": 14901,
          "name": "11test1-3247-173049603",
          "perms": "rw"
        }
      ],
      "symscripts": [],
      "username": "myuser2",
      "volumes": []
    }


Edit Profile
------------

**Type:** :guilabel:`PUT`

.. py:function:: https://cloud.syminet.com/api/v1/users/{USERNAME}/update

    Update ``USERNAME`` to new ``username``, optionally modify ``admin`` privileges.

.. Note::

   Only *primary users* can modify ``admin`` privileges.

**Required URL Parameters:**

USERNAME
  Username to modify.

**Required JSON Properties:**

username
  New username.  Can also be the same, if only modifying ``admin`` privileges.

**Optional:**

admin
  If == "True", grant ``admin`` privileges.  Otherwise **revoke** admin privileges, if enabled.

.. Note::

   For security reasons, revoking ``admin`` privileges by will revoke **all** permissions for 
   the user account.

.. code-block:: shell
   :caption: Curl

    curl --request PUT \
         --url https://cloud.syminet.com/api/v1/users/USERNAME/update \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "username": "mynewusername",
            "admin": "True"
        }
        '

**Response:** :green:`202 OK`


Revoke all Permissions
----------------------

**Type:** :guilabel:`PUT`

.. py:function:: https://cloud.syminet.com/api/v1/users/{USERNAME}/perms/revoke

    Revoke **all** permissions for USERNAME.

.. Note::

   Only *primary users* can modify ``admin`` privileges.

**Required URL Parameters:**

USERNAME
  Username to revoke all permissions for.

.. code-block:: shell
   :caption: Curl

    curl --request PUT \
         --url https://cloud.syminet.com/api/v1/users/USERNAME/perms/revoke \
         --header "authorization:bearer $API_TOKEN"

.. code-block:: json
    :caption: Response

    {
      "admin": false,
      "domains": [],
      "email": "info@syminet.com",
      "firewalls": [],
      "global": {
        "create_domain": false,
        "create_flexip": false,
        "create_fw": false,
        "create_snapshot": false,
        "create_vm": false,
        "create_volume": false,
        "use_api": false
      },
      "id": 2403,
      "slices": [],
      "snapshots": [],
      "username": "myuser2",
      "volumes": []
    }

.. Hint:: 

   The JSON response from this call is a "blank" response for an account with no permissions.
   It might be useful as a JSON template which can be modified locally and :guilabel:`PUT` back 
   to modify user permissions.


Edit Permissions
----------------

**Type:** :guilabel:`PUT`

.. py:function:: https://cloud.syminet.com/api/v1/users/{USERNAME}/perms/update

    Rename volume ``VOLUME_ID``.

**Required URL Parameters:**

USERNAME
  Username to modify.

**Required JSON Properties:**

JSON PAYLOAD
  JSON payload; see note and example directly below.

.. Note::

   To update permissions, you do a PUT wth a JSON payload.  Typically the workflow for this is to 
   retrieve existing perms via API call to :ref:`List User Permissions`. Modify the returned JSON 
   programmatically, and :guilabel:`PUT` it using this call. 

.. Hint::

   For resource types (slices, volumes etc.) the API only cares about the ID and the perms, 
   which are: "ro" (read-only), or "rw" (read-write).  Otherwise no perms are granted.  Other 
   values in the JSON are simply ignored.

.. code-block:: shell
   :caption: Curl

    curl --request PUT \
         --url https://cloud.syminet.com/api/v1/users/USERNAME/perms/update \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
           "admin": false,
           "global": {
             "create_domain": true,
             "create_flexip": true,
             "create_fw": true,
             "create_snapshot": true,
             "create_vm": false,
             "create_volume": true,
             "use_api": false
          },
          "id": 2357,
          "slices": [
            {
              "id": 3219,
              "perms": "ro",
              "vmname": "11test11"
            },
            {
              "id": 3255,
              "perms": "rw",
              "vmname": "11test2"
            }
          ],
          "username": "mnm_sub",
          "volumes": [
            {
              "id": 150,
              "perms": "ro",
              "volname": "my6thvol"
            }
          ]
         }
         '