Authentication
--------------

Access to the API is described below. 

Basic authentication
....................

HTTP basic authentication is defined in section 11.1 of RFC1945, which is simple to implement,
and uses standard HTTP headers.

The HTTP Basic Access Authentication requires authorization credentials in the form
of a user name and password before granting access to resources in the system.
The username and password are passed as Base64 encoded text in the header of API requests.

The HTTP header format for authentication is defined in the table below.

+---------------+------------------------------------+---------------------------------------------------+
| Field Name    | Description                        | Value                                             |
+===============+====================================+===================================================+
| Authorization | Basic authentication is supported. |  Basic [Base64 encoded credentials]               |
+---------------+------------------------------------+---------------------------------------------------+

**Example**:

The Base64 encoded credentials for user name of joe and a password of bloggs.

For example, from a command line 
(note the removal of the new line in the ``echo`` command):

::

  $ echo -n "joe:bloggs" | base64
  am9lOmJsb2dncw==


the header will be:

``Authorization: Basic  am9lOmJsb2dncw==``


For example, using **curl**:

::

   curl -k -H "Authorization: Basic am9lOmJsb2dncw==" 
     'https://hostname/api/data/MyModel/'

It is required that all requests be conducted over a secure session, such as HTTPS or SSL.

A |VOSS Automate| self-signed certificate needs to be installed into a local trust store of the client application.


Session based authentication
............................


See also: :ref:`login-and-auth-tokens`.

Step 1: Log in and retrieve session token
''''''''''''''''''''''''''''''''''''''''''

Use the following ``curl`` command to log in and retrieve the session
token:

::

   curl -k -X POST https://172.30.11.65/noninteractivelogin/ \
     -H "Content-Type: application/json" \
     -d '{
           "username": "<username>",
           "password": "<password>"
         }'

.. rubric:: Example Response


The response includes session-related information in the headers. The
key items to note are:

**Session ID**:

::

   Set-Cookie: sessionid=i6yjbs2t3v2ucwmfe4t67rodrl7mv5nn; HttpOnly; Path=/; SameSite=Lax; Secure

**CSRF Token**:

::

   Set-Cookie: csrftoken=uXBEx0sJ10hmndGcJOmM6lhz7zNs8Fl5dqZ5pkBRSQ2TYqGR5usOh1VhREJS7mHm; HttpOnly; Path=/; SameSite=Lax; Secure
   X-CSRFToken: uXBEx0sJ10hmndGcJOmM6lhz7zNs8Fl5dqZ5pkBRSQ2TYqGR5usOh1VhREJS7mHm


Step 2: Use the session token for subsequent requests
'''''''''''''''''''''''''''''''''''''''''''''''''''''''

For subsequent API requests, include the ``sessionid`` and ``csrftoken``
in the headers.

.. rubric:: Example Command


::

   curl -k -X GET https://172.30.11.65/api/data/User/ \
     -H "Content-Type: application/json" \
     -H "Cookie: sessionid=i6yjbs2t3v2ucwmfe4t67rodrl7mv5nn; csrftoken=uXBEx0sJ10hmndGcJOmM6lhz7zNs8Fl5dqZ5pkBRSQ2TYqGR5usOh1VhREJS7mHm"


Step 3: Session expiry and reauthentication
'''''''''''''''''''''''''''''''''''''''''''

The session token has a **max age** of 1200 seconds (20 minutes), as
indicated in the ``X-Session`` response header:

::

   X-Session: {"max_age": 1200, "expiry": "2025-05-07T13:30:35.354216+00:00", "extendable": true}

If the session expires, you will need to re-login using the same
process in **Step 1** to obtain a new session token.


.. |VOSS Automate| replace:: VOSS
.. |Unified CM| replace:: Unified CM