User Log-on operation

User authentication and authorization is performed by JEA using the JSON Web Tokens (JWT) mechanism. If the client does not yet hold a valid JWT, the Log-on operation must be called to retrieve one. Without a valid JWT, all other transactions will be rejected with HTTP 401 Unauthorized error code.

The user's credential to be sent to the ENSIMS Web Service include the registered email address and the password.

• Method: POST
• Target: https://api.ensims.com/users/api/auth
• cookies: None
• Header: Set Content-Type to application/json
• Body: User credential object
• Success: Auth return object
• Failed: Auth Failed object

{
    "email": "yi@jeplus.org",
    "password": "********"
}

A successful authorization return object contains the status flag, message, user's name, email address, and a new JWT, as shown in the example below.

{
    "ok": true,
    "status": "Logged in successfully!",
    "jwt": "Session token in cookie",
    "user": "Yi",
    "role": null,
    "email": "yi@jeplus.org"
}

{
    "ok": false,
    "status": "No matching username and password pair was found!"
}

Send the check-in command using cURL on Linux:

curl -c cookies -H 'Content-Type: application/json' -X POST -d '{"email": "yi@jeplus.org", "password": "********"}' https://api.ensims.com/users/api/auth

On Windows:

curl -c cookies -H "Content-Type: application/json" -X POST -d "{\"email\": \"yi@jeplus.org\", \"password\": \"********\"}" https://api.ensims.com/users/api/auth

If logged on successfully, an Auth return object with 'OK' status will be received with a new JWT session token. The session token with any other cookies will be saved in the file named cookies as specified by the -c option. If the user's email address and the password do not match any record on the server, and Auth Failed object will be returned.

On Windows, you need to adjust/escape the relevant quote marks.

Make sure Requests is correctly installed in your Python environment, and run the following lines:

import requests

headers = {'Content-Type': 'application/json'}
body = {"email": "yi@jeplus.org", "password": "********"}

# Make a post request with headers and the data body
r = requests.post('https://api.ensims.com/users/api/auth', headers=headers, json=body)

# Store the received session token and any other cookies
cookies = r.cookies

# Show returned information
r.json()

A successful operation will return the JSON content such as the following:

{'email': 'yi@jeplus.org',
 'jwt': 'Session token in cookie',
 'ok': True,
 'status': 'Logged in successfully!',
 'user': 'Yi'}

You can then access each field, e.g. the email address, using r.json()['email'].