pesudev/pesu-auth repository overview

⁠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

⁠How to run PESUAuth locally

Running the PESUAuth API locally is simple. Clone the repository and follow the steps below to get started.

⁠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.

1. Build the Docker image either from the source code or pull the pre-built image from Docker Hub.

   1. 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
      

      Copy

   2. You can also pull the pre-built Docker image from Docker Hub⁠ by running the following command:

      docker pull pesudev/pesu-auth:latest
      

      Copy

2. 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
   

   Copy

3. 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.

1. 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
   

   Copy

2. Run the API using the following command.

   uv run python -m app.app
   

   Copy

3. 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.

⁠/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

⁠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.

⁠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.

⁠/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

⁠/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

import requests

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": "[email protected]",
    "phone": "1234567890",
    "campus_code": 1,
    "campus": "RR"
  },
  "message": "Login successful.",
  "timestamp": "2024-07-28 22:30:10.103368+05:30"
}

⁠cURL

⁠Request

curl -X POST http://localhost:5000/authenticate \
-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⁠.