pesu-auth
A simple and lightweight API to authenticate PESU credentials using PESU Academy.
The API is secure and protects user privacy by not storing any user credentials. It only validates credentials and returns the user's profile information. No personal data is stored.
PESUAuth LIVE Deployment
- You can access the PESUAuth API endpoints here.
- You can view the health status of the API on the PESUAuth Health Dashboard.
API Status
Note
All timestamps are in UTC.
Warning
The live version is hosted on a free tier server located in the United States. As a result, you might experience higher latencies and slower response times, compared to running the API locally or on a server closer to your location.
How to run PESUAuth locally
Running the PESUAuth API locally is simple. Clone the repository and follow the steps below to get started.
Tip
We recommend running the API locally using Docker for ease of use, the best performance, and lowest latency.
Running with Docker
This is the easiest and recommended way to run the API locally. Ensure you have Docker installed on your system. Run the following commands to start the API.
-
Build the Docker image either from the source code or pull the pre-built image from Docker Hub.
-
You can build the Docker image from the source code by running the following command in the root directory of the repository.
docker build . --tag pesu-auth -
You can also pull the pre-built Docker image from Docker Hub by running the following command:
docker pull pesudev/pesu-auth:latest
-
-
Run the Docker container
docker run --name pesu-auth -d -p 5000:5000 pesu-auth
# If you pulled the pre-built image, use the following command instead:
docker run --name pesu-auth -d -p 5000:5000 pesudev/pesu-auth:latest -
Access the API at
http://localhost:5000/
Running without Docker
If you don't have Docker installed, you can run the API natively. Ensure you have Python 3.11 or higher
installed on your system. We recommend using a package manager like uv to manage
dependencies.
-
Create a virtual environment using and activate it. Then, install the dependencies using the following commands.
uv venv --python=3.11
source .venv/bin/activate
uv sync -
Run the API using the following command.
uv run python -m app.app -
Access the API as previously mentioned on
http://localhost:5000/
How to use the PESUAuth API
The API provides multiple endpoints for authentication, documentation, and monitoring.
| Endpoint | Method | Description |
|---|---|---|
/ |
GET |
Serves the interactive API documentation (Swagger UI). |
/authenticate |
POST |
Authenticates a user using their PESU credentials. |
/health |
GET |
A health check endpoint to monitor the API's status. |
/readme |
GET |
Redirects to the project's official GitHub repository. |
/authenticate
You can send a request to the /authenticate endpoint with the user's credentials and the API will return a JSON
object, with the user's profile information if requested.
Request Parameters
| Parameter | Optional | Type | Default | Description |
|---|---|---|---|---|
username |
No | str |
The user's SRN or PRN | |
password |
No | str |
The user's password | |
profile |
Yes | boolean |
False |
Whether to fetch profile information |
fields |
Yes | list[str] |
None |
Which fields to fetch from the profile information. If not provided, all fields will be fetched |
Response Object
On authentication, it returns the following parameters in a JSON object. If the authentication was successful and
profile data was requested, the response's profile key will store a dictionary with a user's profile information.
On an unsuccessful sign-in, this field will not exist.
| Field | Type | Description |
|---|---|---|
status |
boolean |
A flag indicating whether the overall request was successful |
profile |
ProfileObject |
A nested map storing the profile information, returned only if requested |
message |
str |
A message that provides information corresponding to the status |
timestamp |
datetime |
A timezone offset timestamp indicating the time of authentication |
ProfileObject
This object contains the user's profile information, which is returned only if the profile parameter is set to True.
If the authentication fails, this field will not be present in the response.
| Field | Description |
|---|---|
name |
Name of the user |
prn |
PRN of the user |
srn |
SRN of the user |
program |
Academic program that the user is enrolled into |
branch |
Complete name of the branch that the user is pursuing |
semester |
Current semester that the user is in |
section |
Section of the user |
email |
Email address of the user registered with PESU |
phone |
Phone number of the user registered with PESU |
campus_code |
The integer code of the campus (1 for RR and 2 for EC) |
campus |
Abbreviation of the user's campus name |
/health
This endpoint can be used to check the health of the API. It's useful for monitoring and uptime checks. This endpoint does not take any request parameters.
Response Object
| Field | Type | Description |
|---|---|---|
status |
str |
true if healthy, false if there was an error |
message |
str |
"ok" if healthy, error message otherwise |
timestamp |
string |
A timezone offset timestamp indicating the time of authentication |
/readme
This endpoint redirects to the project's official GitHub repository. This endpoint does not take any request parameters.
Integrating your application with the PESUAuth API
Here are some examples of how you can integrate your application with the PESUAuth API using Python and cURL.
Python
Request
data = {
"username": "your SRN or PRN here",
"password": "your password here",
"profile": True, # Optional, defaults to False
}
response = requests.post("http://localhost:5000/authenticate", json=data)
print(response.json())
Response
"status": true,
"profile": {
"name": "Johnny Blaze",
"prn": "PES1201800001",
"srn": "PES1201800001",
"program": "Bachelor of Technology",
"branch": "Computer Science and Engineering",
"semester": "NA",
"section": "NA",
"email": "johnnyblaze@gmail.com",
"phone": "1234567890",
"campus_code": 1,
"campus": "RR"
},
"message": "Login successful.",
"timestamp": "2024-07-28 22:30:10.103368+05:30"
}
cURL
Request
-H "Content-Type: application/json" \
-d '{
"username": "your SRN or PRN here",
"password": "your password here"
}'
Response
"status": true,
"message": "Login successful.",
"timestamp": "2024-07-28 22:30:10.103368+05:30"
}
Contributing to PESUAuth
Made with by
Powered by contrib.rocks
If you'd like to contribute, please follow our contribution guidelines.