How to Authenticate

Catalyst Manager REST API access control is based on sessions. All users will be able to get a session after successfully logging in. The following are typical steps for a user to consume the API:

Log in with a user name and password to establish a session:

POST /j_security_check with content type x-www-form-urlencoded. The user name and password are submitted as j_username and j_password. The session token is in the response http cookie, JSESSIONID={session hash}.
```
POST https://{vmanage-ip-address}/j_security_check
Content-Type: application/x-www-form-urlencoded
HTTP Body: "j_username={admin}&j_password={credential}"
```
If a user is successfully authenticated, the response body is empty and a valid session cookie is set is response (set-cookie: JSESSIONID=). If a user is un-authenticated, the response body contains a html login page with tag in it. API client should check the response body for to identify whether the authentication is successful or not. This is the behavior of our application server.
Get a cross-site request forgery prevention token, which is required for most POST operations:

GET /dataservice/client/token with content type application/json. The JESSIONID={session hash} cookie is required to authenticate.
The XSRF token is in the response body. Use the XSRF token along with the JESSIONID cookie for ongoing API requests.
```
GET https://{vmanage-ip-address}/dataservice/client/token
Content-Type: application/json
HTTP Header: "Cookie: JESSIONID={session hash id}"
```
Make an API request

For non-whitelisted endpoints, the user needs to provide an API token as a cookie: JESSIONID={session hash}.

For POST requests, the user also needs to provide the matching XSRF token.
```
https://{vmanage-ip-address}/dataservice/{api-endpoint-url}
Content-Type: application/json
HTTP Header: "Cookie: JESSIONID={session hash id}" "X-XSRF-TOKEN: {XSRF token}"
```
Log out and destroy the session

The user needs to log out after finishing the API requests. This is not only a good security practice, but also releases the allocated session resource.

If the http response code is 302 redirect with location header https://{vmanage-ip-address}/welcome.html?nocache=, the session has been invalidated. Otherwise, an error occurred in the session invalidation process.
```
POST https://{vmanage-ip-address}/logout?nocache={random-number}`  
HTTP Header: "Cookie: JESSIONID={session hash id}"
```
Sample code to authenticate with Catalyst Manager:

class Authentication:

    @staticmethod
    def get_jsessionid(vmanage_host, vmanage_port, username, password):
        api = "/j_security_check"
        base_url = "https://%s:%s"%(vmanage_host, vmanage_port)
        url = base_url + api
        payload = {'j_username' : username, 'j_password' : password}

        response = requests.post(url=url, data=payload, verify=False)
        try:
            cookies = response.headers["Set-Cookie"]
            jsessionid = cookies.split(";")
            return(jsessionid[0])
        except:
            print("No valid JSESSION ID returned\n")
            exit()

    @staticmethod
    def get_token(vmanage_host, vmanage_port, jsessionid):
        headers = {'Cookie': jsessionid}
        base_url = "https://%s:%s"%(vmanage_host, vmanage_port)
        api = "/dataservice/client/token"
        url = base_url + api      
        response = requests.get(url=url, headers=headers, verify=False)
        if response.status_code == 200:
            return(response.text)
        else:
            return None

Auth = Authentication()
jsessionid = Auth.get_jsessionid(vmanage_host,vmanage_port,vmanage_username,vmanage_password)
token = Auth.get_token(vmanage_host,vmanage_port,jsessionid)

if token is not None:
    header = {'Content-Type': "application/json",'Cookie': jsessionid, 'X-XSRF-TOKEN': token}
else:
    header = {'Content-Type': "application/json",'Cookie': jsessionid}

Note:

API requests header for GET/POST/PUT/DELETE are

For Catalyst Manager pre-19.2 - Session Cookie (jsessionid)
For Catalyst Manager post-19.2 - Session Cooke (jsessionid) and Token

It is mandatory to share the same session if multiple API requests are invoked sequentially. The default session lifespan is 24 hours, and the session inactivity timeout is 30 minutes.

The maximum concurrent session number is 100. The new session will invalidate the least recently used session if the maximum concurrent session number is reached.

How to Authenticate in SSO Enabled Catalyst Manager

If SSO authentication is enabled on Catalyst Manager, you can copy the JSESSIONID and X-XSRF-Token from your browser to authenticate an API request.

Login to Catalyst Manager via SSO in your browser.
From your browser's developer tool, select the "Network" tab.
Inspect an API request.
From the API request headers, copy the value of "Cookie: JSESSIONID=" and "X-XSRF-TOKEN: ".
Use the JSESSIONID and X-XSRF-TOKEN for API authentication.