login

POST public/login

Signs in to the SC//AcuVigil API and starts a session. The API returns a session cookie. Send that cookie with later calls instead of sending your credentials each time.

Request syntax

curl https://apiv2.acumera.net/public/login \
  --cookie-jar av_session.txt \
  --data-urlencode "username=<username>" \
  --data-urlencode "password=<password>" \
  --data-urlencode "tfa_token=<2fa_code>"

--cookie-jar av_session.txt saves the session cookie to the file av_session.txt. Send it with later calls by using --cookie av_session.txt. For more information, see Getting started with the SC//AcuVigil API.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter	Type	Description	Required
`username`	String	Your SC//AcuVigil username (your email address).	Yes
`password`	String	Your SC//AcuVigil password.	Yes
`tfa_token`	String	The current code from your two-factor authentication (2FA) app.	Yes

Response syntax

{
    "success": "string",
    "returnCode": "string",
    "returnMessage": "string"
}

Response parameters

Field	Description
`success`	`"1"` if you're signed in, `"0"` if you aren't.
`returnCode`	`LOGIN_SUCCESSFUL` when you're signed in.
`returnMessage`	A description of the result.

If the call succeeds, the response also sets the session cookie.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code	Message	Cause
`AUTH_FAILED_NO_USER`	Authentication failed because no username was provided.	`username` is missing or empty.
`AUTH_FAILED_NO_PASSWORD`	Authentication failed because no password was provided.	`password` is missing or empty.
`AUTH_FAILED_NO_TOKEN`	Authentication failed because no 2FA token was provided.	`tfa_token` is missing or empty.
`INVALID_LOGIN`	We were unable to log you in. Make sure you entered the correct username, password and 2FA code.	The username, password, or 2FA code is wrong, or the 2FA code has expired.
`PASSWORD_RESET_DUE`	Your password has expired. You will need to reset it before logging in.	Your password has expired. Change it with changePassword.

Examples

curl https://apiv2.acumera.net/public/login \
  --cookie-jar av_session.txt \
  --data-urlencode "username=pat@example.com" \
  --data-urlencode "password=<password>" \
  --data-urlencode "tfa_token=123456"

Response:

{
    "success": "1",
    "returnCode": "LOGIN_SUCCESSFUL",
    "returnMessage": "Login successful."
}

{
    "success": "0",
    "returnCode": "INVALID_LOGIN",
    "returnMessage": "We were unable to log you in. Make sure you entered the correct username, password and 2FA code."
}

Get a new code from your 2FA app and sign in again.