Navigation :

Login

Introduction

The HTTP API provides three special request endpoints to handle general authentication. The endpoints are __status, __login and __logout.

Status

A status request, made to the endpoint __status can be made at any time to retreive the current authenticated user and their authorization. information is provided in a JSON object with the following fields:

Key	Type	Description
`error_string`	String	If the user is not logged in, or another error occurs, the error will be described in this field.
`group_list`	String	If authenticated this field will exist and provide a comma separate list of groups the user has been authenticated with.
`logged_in`	Integer	If 1, the user is logged in. If 0, the user is not logged in.
`sid`	String	The Session ID of the user. This session ID is also sent through in a cookie, the name of which will depend on site-specific configuration, the default for which is `N2FE_CGISESSID`.
`sid_param`	String	The name of the cookie where the SID is stored.
`username`	String	If authenticated this field will exist and privide the username the user is logged in with.

Example

Request:

curl 'http://localhost/jarvis-agent/n2fe/__status'

Response when a user is logged in:

{
   "sid" : "82574d58af7ec60891970596be3b9508",
   "version" : "development",
   "license" : {
      "license_error" : null,
      "packages" : {},
      "licensed" : 1,
      "notes" : "\nThis is an limited license for use only by authorised agents of N-Squared \nstrictly for the sole purpose of performing demonstrations.\n\nUse of this license by any unauthorised person or in any other environment \nis strictly forbidden and legal penalties may apply.\n        ",
      "licensee" : "N-Squared Software (NZ) Ltd [Demonstration Use Only]",
      "licensed_until_description" : " 1st January 2020"
   },
   "user_info" : {
      "acs_customer_restriction_list" : null,
      "user_id" : "su",
      "user_timezone" : "Australia/Sydney",
      "user_type" : "SMS"
   },
   "group_list" : "ACS_BOSS,BCD_BOSS,CCS Superuser",
   "sid_param" : "N2FE_CGISESSID",
   "logged_in" : 1,
   "username" : "su",
   "error_string" : ""
}

Response when a user is not yet logged in:

{
   "sid_param" : "N2FE_CGISESSID",
   "group_list" : "",
   "error_string" : "No credentials supplied.",
   "version" : "development",
   "username" : "",
   "license" : {
      "packages" : {},
      "licensee" : "N-Squared Software (NZ) Ltd [Demonstration Use Only]",
      "notes" : "\nThis is an limited license for use only by authorised agents of N-Squared \nstrictly for the sole purpose of performing demonstrations.\n\nUse of this license by any unauthorised person or in any other environment \nis strictly forbidden and legal penalties may apply.\n        ",
      "licensed" : 1,
      "licensed_until_description" : " 1st January 2020",
      "license_error" : null
   },
   "logged_in" : 0,
   "sid" : "82574d58af7ec60891970596be3b9508"
}

Login is performed via the special API endpoint __status. The username and password for the login may be passed through in JSON within the request body.

Parameter	Example	Description
`username`	su	The user to log in.
`password`	boss	The password the user has provided.
`recaptcha_response`		The recaptcha value matching the CAPTCHA displayed to the user, if enabled via configuration.

The response will be provided in a JSON object. See the __status response details in the previous section for details on the response content.

The API endpoint __login may be used as an alias for __status if desired.

Example

Request:

curl -v --data '{"username": "su", "password": "boss"}' 'http://localhost/jarvis-agent/n2fe/__status'

Response:

{
   "user_info" : {
      "acs_customer_restriction_list" : null,
      "user_type" : "SMS",
      "user_id" : "su",
      "user_timezone" : "Australia/Sydney"
   },
   "license" : {
      "licensed_until_description" : " 1st January 2020",
      "notes" : "\nThis is an limited license for use only by authorised agents of N-Squared \nstrictly for the sole purpose of performing demonstrations.\n\nUse of this license by any unauthorised person or in any other environment \nis strictly forbidden and legal penalties may apply.\n        ",
      "license_error" : null,
      "licensed" : 1,
      "packages" : {},
      "licensee" : "N-Squared Software (NZ) Ltd [Demonstration Use Only]"
   },
   "sid" : "0928c58f93831fc4fff5fbbc52181215",
   "version" : "development",
   "error_string" : "",
   "group_list" : "ACS_BOSS,BCD_BOSS,CCS Superuser",
   "username" : "su",
   "sid_param" : "N2FE_CGISESSID",
   "logged_in" : 1
}

The response provides the sid_param and sid, which should be used as the HTTP cookie name and cookie value for subsequent requests. The response also uses the Set-Cookie header to set this automatically for tools (such as web browsers) that monitor for the header.

logout

Logout is performed by making a call using any method to the __logout endpoint:

Example

Request:

curl 'http://localhost/jarvis-agent/n2fe/__logout' -H 'Cookie: N2FE_CGISESSID=4876c530f3d7252330a95ea51007f252'

Response:

{
   "logged_in" : 0,
   "group_list" : "",
   "sid_param" : "N2FE_CGISESSID",
   "license" : {
      "licensed" : 1,
      "packages" : {},
      "license_error" : null,
      "licensed_until_description" : " 1st January 2020",
      "licensee" : "N-Squared Software (NZ) Ltd [Demonstration Use Only]",
      "notes" : "\nThis is an limited license for use only by authorised agents of N-Squared \nstrictly for the sole purpose of performing demonstrations.\n\nUse of this license by any unauthorised person or in any other environment \nis strictly forbidden and legal penalties may apply.\n        "
   },
   "error_string" : "Logged out at client request.",
   "version" : "development",
   "sid" : "",
   "username" : ""
}