Retrieve session ID using login API

Before you begin

Make sure you have valid login credentials (Username and Password) for accessing the system.
You cannot use OAuth credentials (Client ID and Client Secret) for login.
To access the APIs using the service token, use the API with the Service Account.

Request Structure


Endpoint	`/login`
Type	`POST`
Sample URL	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/login?&gwsource=external` To understand the elements of the sample URL, click here.
Headers
Content-Type	application/json
Request timeout period	15 minutes

Table 1. Input Parameters
	Description
username `Header`	(Mandatory) User login name of the user. Type: String Example: "admin"
password `Header`	(Mandatory) Password for the username. Type: String Example: "Password@123"
otp `Header`	(Mandatory only if MFA is enabled) If MFA is enabled, enter the OTP received on your registered email ID in the header. Multifactor authentication (MFA) is a security mechanism that requires users to provide two or more verification factors to gain access to a resource If MFA is enabled, and you try to login with only the username and password, you will get the following error upon execution of the API: MFA is enabled. We have sent an OTP to your email ID: aaa****[email protected]. In this case, ensure that the OTP is included in the header and try logging in again. Type: String Example: "OTP : 609700"
Content-Type `Header`	(Mandatory) The parameter should be set to `application/json` to specify the nature of the data in the payload. Type: String Example: "application/json"
gwsource `Query`	(Mandatory) Source from which the request is triggered. The values can be: web external Type: String

Response Structure

Status Code: 200 Ok
Message: Login Successful
Headers:
- Content-Type: application/json

Table 2. Response Parameters
Name	Description
response	The response contains the attributes needed to retrieve the session ID.
message	Success message or failure description in case of error.
appStatusCode	Application specific status code for the response. Will be non-null for failure response.
tags	More info in case of failure response.


Name	Description
status	Indicates the overall status of the response. The values can be: SUCCESS FAILURE
appStatusCode	An application-specific status code, if applicable.
statusDescription	Description of the status, if available.
sessionId	Unique identifier for the session.
lockDownPeriod	Number of login attempts remaining.
termsAccepted
passwordExpiryMsg
emailId

Status Codes


HTTP Code	appStatusCode	Response Message
200 OK	NA	Login successful
400 Bad request	ACCT_AUTH_001	Username or password cannot be null or empty.
401 Unauthorized	ACC_AUTH_022	Login failed. Invalid credentials.
401 Unauthorized	ACC_AUTH_006	Login failed. Invalid credentials.

Sample Request/Response

Use Case

Log in to the application with a username and password.

Sample Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/login?&gwsource=external

Request Payload

{}

Sample Response

{
    "response": {
        "status": "SUCCESS",
        "appStatusCode": null,
        "statusDescription": null,
        "sessionId": "avx~~c73a4f56-f4ab-4cdf-aadf-6d90bf406077",
        "authCode": null,
        "lockDownPeriod": 15,
        "emailId": null,
        "termsAccepted": true,
        "passwordExpiryMsg": ""
    },
    "message": "Login successful.",
    "appStatusCode": null,
    "tags": null,
    "headers": null
}

Reference

Understanding the sample URL: This section provides an explanation of each component of the sample URL structure used in API requests. For quick reference, this section is referenced in all the API topics as Reference in this guide.

IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify
  The tenant name will be included in the endpoint URL for a SaaS deployment.
GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: execute-hook
gwsource: Source or origin of a gateway, for example: external.

What can you do next?

After the sessionID ris etrieved using the login API, you can nowuse the session ID for API calls.