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 self-signed certificate needs to be installed into a local trust store of the client application.

Session based authentication

See also: Login and Authorization 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>"
      }'

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.

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.