# Authentication

# Introduction

Akixi Application uses a password-based authentication mechanism. Most Akixi features are only available to authenticated Users - therefore, authentication-related steps normally precede all other API requests.

Authentication procedure consists of three operations:

• Create Session
• Login
• Logout

# Create Session

The first step in the authentication process is to create the Akixi service session. The user has to then authenticate the session using Basic authentication, for more details see Login request documentation page. Once the session is authenticated, it must be used as JSESSIONID cookies authentication with all requests.

# Request

# HTTP Method

• POST

# URL Endpoint

/session

# Parameters:

There are no query parameters.

# Body

There is no request body.

# Sample URL

https://sampleurl.akixi.com/CCS/API/v1/session

# Response

# Example Of A Successful Result With 200 HTTP Status Code:

{
    "Nonce": "20d5e39b41c7016d3ec9e647ccdbac1f",
    "SessionID": "D199F7ED33E35249933A20CA07387C43"
}

# Fields:

# Nonce

• type: string

The cryptographic string that could be used only once in authentication flow.

# SessionID

• type: string

The identifier of the Akixi service user session which must subsequently be used in all requests as JSESSIONID cookie.

# Code Snippets

See the following code snippets to help you start with the integration:

curl -X POST \
  'https://host/CCS/API/v1/session'

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === XMLHttpRequest.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://host/CCS/API/v1/session);
xhr.send(data);

import http.client

conn = http.client.HTTPConnection("host")
headers = {}

conn.request("POST", "CCS,API,v1,session", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

// http://unirest.io/ used in the snippet.
HttpResponse<String> response = Unirest.post("https://host/CCS/API/v1/session)
  .asString();

# Login

The session created using Create Session request has to be authenticated. v1 API version supports HTTP Basic authentication to authenticate a user.

# Request

# HTTP Method

• GET

# Endpoint

/login

# Parameters:

# Body

There is no request body.

# Sample URL

https://sampleurl.akixi.com/CCS/API/v1/login?locale=en_GB

# Response

In case of successful authentication the 200 HTTP status code is returned with empty response body.

# Code Snippets

See the following code snippets to help you start with the integration:

curl -X GET \
  'https://host/CCS/API/v1/login?&locale=en_GB' \
  -H 'Authorization: Basic VXNlcjpVc2Vy' \
  -H 'Cookie: JSESSIONID=2F6C4C46E372F89414388BD9A8429785;'

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === XMLHttpRequest.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://host/CCS/API/v1/login?locale=en_GB");
xhr.setRequestHeader("Authorization", "Basic VXNlcjpVc2Vy");
xhr.setRequestHeader("Cookie", "JSESSIONID=2F6C4C46E372F89414388BD9A8429785;");
xhr.send(data);

import http.client

conn = http.client.HTTPConnection("host")
headers = {
    'Authorization': "Basic VXNlcjpVc2Vy",
    'Cookie': "JSESSIONID=18A3790412841327CE46E15EFC8CADCB;"
}

conn.request("GET", "CCS,API,v1,login", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

// http://unirest.io/ used in the snippet.
HttpResponse<String> response = Unirest.get("https://host/CCS/API/v1/login?locale=en_GB")
  .header("Authorization", "Basic VXNlcjpVc2Vy")
  .header("Cookie", "JSESSIONID=2F6C4C46E372F89414388BD9A8429785;")
  .asString();

# Logout

A User must be logged out in order to explicitly end the API session, which immediately frees up server-side resources and also improves security.

# Request

# HTTP Method

• GET

# Endpoint

/logout

# Parameters:

There are no query parameters.

# Body

There is no request body.

# Sample URL

https://sampleurl.akixi.com/CCS/API/v1/logout

# Response

In case of successful log out action the 200 HTTP status code is returned with empty response body.

# Code Snippets

See the following code snippets to help you start with the integration:

curl -X GET \
  'https://host/CCS/API/v1/logout' \
  -H 'Cookie: JSESSIONID=2F6C4C46E372F89414388BD9A8429785;'

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === XMLHttpRequest.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://host/CCS/API/v1/logout");
xhr.setRequestHeader("Cookie", "JSESSIONID=2F6C4C46E372F89414388BD9A8429785;");
xhr.send(data);

import http.client

conn = http.client.HTTPConnection("host")
headers = {
    'Cookie': "JSESSIONID=2F6C4C46E372F89414388BD9A8429785;"
}

conn.request("GET", "CCS,API,v1,logout,", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

// http://unirest.io/ used in the snippet.
HttpResponse<String> response = Unirest.get("https://host/CCS/API/v1/logout")
  .header("Cookie", "JSESSIONID=2F6C4C46E372F89414388BD9A8429785;")
  .asString();

# Security

# Recommendations On Security

Akixi User credentials must be treated as confidential & sensitive information. Therefore, developers and users working on/with REST API should carefully evaluate a password protection scheme that will provide a reasonable level of security. For example, you must avoid bad practices like storing Akixi credentials in clear text within unencrypted configuration files, key-stores, and/or database fields, especially if publicly accessible directly or indirectly. All security-related scenarios must be evaluated and tested in order to avoid security breaches caused by client-side vulnerabilities.

# Brute Force Attack Prevention

If a user authentication attempt fails due to incorrect credentials, you will get 3 attempts before the application will temporarily lock out the corresponding User account for a period of 5 seconds. Subsequent failed password attempts will double the temporary lock out period (i.e. to 10 seconds, 20 seconds, etc.).
After several failed authentication attempts, your account will be permanently disabled and you will have to refer the problem to your Application Provider in order to get that particular User account unlocked.

# Session Timeouts

Once signed in, your session can expire due to inactivity. Session inactivity timeout is 30 minutes where you will be automatically logged out if your API session remains inactive for 30 minutes or more. Although your session will naturally expire when left inactive, we strongly recommend that developers explicitly invoke the Logout request whenever the API session is no longer required.