Vui current state rebased

docs/source/index.rst

@@ -136,6 +136,7 @@ at our bi-weekly office-hours and on Slack. To be invited to office-hours or sla
    platform-features/control/index
    platform-features/config-store/configuration-store
    platform-features/security/volttron-security
+   platform-features/web-api/introduction
 
 
 .. toctree::

docs/source/platform-features/web-api/agent-endpoints.rst

@@ -0,0 +1,104 @@
+================
+Agents Endpoints
+================
+
+Agents endpoints expose functionality associated with applications
+running on a VOLTTRON platform.
+
+Agents endpoints currently include:
+
+    * `RPC <rpc-endpoints.html>`_: Endpoints allowing, discovery, inspection, and calling of remote procedure calls to agents running on the platform.
+
+.. attention::
+    All Agent endpoints require a JWT bearer token obtained through the
+    ``POST /authenticate`` or ``PUT /authenticate`` endpoints.
+
+--------------
+
+GET /platforms/:platform/agents
+===============================
+
+Return routes for the agents installed on the platform.
+
+Accepts a two query parameters:
+
+    * ``agent-state`` accepts one of three string values:
+
+        - *"running"* (default): Returns only those agents which are currently running.
+        - *"installed"*: Returns all installed agents.
+        - *"packaged"*: Returns filenames of packaged agents on the platform which can be installed.
+    * ``include-hidden`` (default=False): When True, includes system agents which would not normally be displayed by vctl status.
+
+Request:
+--------
+
+    -  Authorization: ``BEARER <jwt_access_token>``
+
+Response:
+---------
+
+    * **With valid BEARER token on success:** ``200 OK``
+        - Content Type: ``application/json``
+        - Body:
+
+            .. code-block:: JSON
+
+                {
+                    "route_options": {
+                        "<vip_identity>": "/platforms/:platform/agents/:vip_identity",
+                        "<vip_identity>": "/platforms/:platform/agents/:vip_identity"
+                    }
+                }
+
+    * **With valid BEARER token on failure:** ``400 Bad Request``
+        - Content Type: ``application/json``
+        - Body:
+
+            .. code-block:: JSON
+
+                {
+                    "error": "<Error Message>"
+                }
+
+    * **With invalid BEARER token:** ``401 Unauthorized``
+
+------------------------------------------------------------------------------------------
+
+GET /platforms/:platform/agents/:vip-identity
+=============================================
+
+Return routes for the supported endpoints for an agent installed on the platform.
+Currently implemented endpoints include `RPC <rpc-endpoints.html>`_.
+
+Request:
+--------
+
+    -  Authorization: ``BEARER <jwt_access_token>``
+
+Response:
+---------
+
+    * **With valid BEARER token on success:** ``200 OK``
+        - Content Type: ``application/json``
+        - Body:
+
+            .. code-block:: JSON
+
+                {
+                    "route_options": {
+                        "<vip_identity>": "/platforms/:platform/agents/:vip_identity/<endpoint1_name>",
+                        "<vip_identity>": "/platforms/:platform/agents/:vip_identity/<endpoint2_name>"
+                    }
+                }
+
+    * **With valid BEARER token on failure:** ``400 Bad Request``
+        - Content Type: ``application/json``
+        - Body:
+
+            .. code-block:: JSON
+
+                {
+                 "error": "<Error Message>"
+                }
+
+    * **With invalid BEARER token:** ``401 Unauthorized``

docs/source/platform-features/web-api/authentication-endpoints.rst

@@ -0,0 +1,113 @@
+.. _Authentication-Endpoints:
+
+========================
+Authentication EndPoints
+========================
+
+The VOLTTRON Web API requires the use of bearer tokens to access resources.  These tokens
+are JSON Web Tokens (JWT) and are provided by the two ``/authenticate`` endpoints (``POST``
+and ``PUT``).  Two classes of token are provided to the user:
+
+- Refresh Tokens:
+    Refresh tokens are long-lived, and used can be used to obtain a new short-lived access
+    token. Refresh tokens are obtained by providing a valid username and password to the
+    ``POST /authenticate`` endpoint. The refresh token SHOULD be kept secure on the
+    client side, and SHOULD NOT be provided to API call other than to
+    ``PUT /authenticate``.
+
+- Access Tokens:
+    An access token are short-lived tokens required to obtain resources or services provided
+    by other API endpoints. The access token is obtained using the ``PUT /authenticate``
+    endpoint. For convenience, an inital access token is provided by the
+    ``POST /authenticate`` endpoint as well, but as use the ``POST`` method requires
+    sending credentials to the server, this should only be used on the first call, with
+    ``PUT`` being used thereafter to obtain new access tokens until the refresh token has
+    also expired.
+
+.. note:: Authentication begins by obtaining a JWT bearer refresh token from the
+    ``POST /authenticate`` endpoint. An initial access token is provided by this endpoint
+    as well. Subsequent access tokens are then obtained by providing the refresh token to the
+    ``PUT /authenticate`` endpoint without resending of credentials.
+
+----------------------------------------------------------------------------
+
+POST /authenticate
+==================
+
+Provide authentication credentials to receive refresh token.
+
+The user provides a username and password in the request body. If authentication succeeds,
+the endpoint will returna a JWT bearer refresh token with user’s claims. An initial access
+token is also returned. The refresh token can then be provided to ``PUT /authenticate``
+to obtain new short-lived access tokens, as needed, without sending the username and
+password again until the refresh token expires.
+
+Request:
+--------
+    - Content Type: ``application/json``
+    - Body:
+
+        .. code-block:: JSON
+
+            {
+                "username": "<username>",
+                "password": "<password>"
+            }
+
+Response:
+---------
+
+    * **With valid username and password:** ``200 OK``
+        - Content Type: ``application/json``
+        - Body:
+
+            .. code-block:: JSON
+
+                {
+                    "refresh_token": "<jwt_refresh_token>",
+                    "access_token": "<jwt_access_token>"
+                }
+
+    * **With invalid username and password:** ``401 Unauthorized``
+
+--------------
+
+PUT /authenticate
+=================
+
+Renew access token.
+
+    The user provides a valid refresh token (provided by ``POST /authenticate``) in the
+    Authorization header to obtain a fresh access token. A current access token MAY also
+    be provided, as needed, in the request body to keep open any existing subscriptions.
+    All subsequent requests to any endpoint should include the new token, and the old
+    access token should be discarded.
+
+Request:
+--------
+
+    - Content Type: ``application/json``
+    - Authorization: ``BEARER <jwt_refresh_token>``
+    - Body (optional):
+
+        .. code-block:: JSON
+
+            {
+              "current_access_token": "<jwt_access_token>"
+            }
+
+Response:
+---------
+
+* **With valid refresh token:** ``200 OK``
+    - Content Type: ``application/json``
+    - Body:
+
+        .. code-block:: JSON
+
+            {
+                "access_token": "<new_jwt_access_token>"
+            }
+
+* **With invalid or mismatched username, password, or token:**
+   ``401 Unauthorized``