JSON API » user » user/login

Gets the login data for the authentication user, based on the person logging in as.

If the user has TOTP (two-factor authentication) enabled, the login is a two-step process. First call without auth_code to receive a 202 response containing a temporary token. Then call again with that token and the TOTP code to complete login.

Input parameters

Requires authentication and the user role privilege.

Name	Type	Description	Required	Default value
auth_username	String	Authentication username. Required for step 1.	Yes (step 1)
auth_password	String	Authentication password. Required for step 1.	Yes (step 1)
auth_code	String	TOTP code from authenticator app. Supply in step 1 for one-step login, or in step 2 for two-step login.	No
totp_token	String	Temporary token received in the 202 response. Triggers step 2 TOTP validation when supplied.	No
token	Integer	1 to get an authentication token, 0 not to.	No	0

Responses

Code	Description
200	Success.
202	Password correct but TOTP code required. Returns totp_token, username, and totp_required in data. Use the token in a second call with auth_code to complete login.
401	The authentication details provided are invalid, or the TOTP token is invalid or expired.
402	Your role does not allow this.

Data returned (200)

Fields of user.

Data returned (202)

Field	Type	Description
totp_required	Boolean	Always true.
totp_token	String	Temporary JWT to use in the second login call. Valid for 2 minutes.
username	String	The username that was authenticated.

Example: Login without TOTP

http://enswitch.example.com/api/json/user/login/?auth_username=user;auth_password=password

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ], "data":{ "id":123, "username":"user", ... } }

Example: Step 1 - Password only (TOTP required)

http://enswitch.example.com/api/json/user/login/?auth_username=user;auth_password=password

{ "responses":[ { "code":"202", "key":"", "message":"OK" } ], "data":{ "totp_required":true, "totp_token":"eyJ...", "username":"user" } }

Example: Step 2 - TOTP code with temporary token

http://enswitch.example.com/api/json/user/login/?totp_token=eyJ...;auth_code=123456

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ], "data":{ "id":123, "username":"user", ... } }

Example: One-step login (password and TOTP code together)

http://enswitch.example.com/api/json/user/login/?auth_username=user;auth_password=password;auth_code=123456

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ], "data":{ "id":123, "username":"user", ... } }

Change history

Version	Changes
4.4	TOTP two-step login support added: auth_code, totp_token parameters added; 202 response added.
4.1	token input parameter added.
3.13	Function added.