Tokens and Captcha

Purpose and Scope

This document describes the captcha-related data structures in pyjiit, specifically the Captcha class defined in pyjiit/tokens.py The Captcha class encapsulates the captcha challenge and response data required during student authentication.

For information about the complete authentication flow, see Authentication Flow. For session management after authentication, see Session Management.

Captcha Class Overview

The Captcha class is a dataclass that represents a captcha challenge issued by the JIIT Webportal. It contains three components: the captcha answer text, a hidden identifier, and the captcha image encoded as base64.

Sources: pyjiit/tokens.py1-29

Class Structure

Sources: pyjiit/tokens.py3-28 pyjiit/wrapper.py111-143 pyjiit/wrapper.py145-154 pyjiit/default.py1-8

Field Descriptions

The Captcha dataclass contains the following fields:

Sources: pyjiit/tokens.py4-10

Methods

payload()

def payload(self) -> dict

Converts the captcha data to a dictionary format suitable for API requests.

Returns: A dictionary containing only the captcha answer and hidden identifier fields. The image field is excluded as it is not needed in API payloads.

Return Structure:

{
    "captcha": str,  # The captcha answer text
    "hidden": str    # The captcha identifier
}

Sources: pyjiit/tokens.py12-19

from_json()

@staticmethod
def from_json(resp: dict) -> 'Captcha'

Factory method that constructs a Captcha object from the API response JSON.

Parameters:

• resp: Dictionary containing the API response with nested captcha data

Returns: A new Captcha instance populated with data from the response

Expected Response Structure:

{
    "captcha": {
        "captcha": str,  # Captcha answer
        "hidden": str,   # Captcha identifier
        "image": str     # Base64-encoded PNG image
    }
}

Sources: pyjiit/tokens.py21-27

Usage in Authentication Flow

The Captcha class is used in the two-phase student login process. The following diagram illustrates how captcha data flows through the authentication system:

Sources: pyjiit/wrapper.py111-143 pyjiit/wrapper.py145-154

Webportal Methods Using Captcha

get_captcha()

The Webportal.get_captcha() method retrieves a new captcha challenge from the JIIT API.

Location: pyjiit/wrapper.py145-154

Endpoint: GET /token/getcaptcha

Returns: A Captcha object with the captcha field initially empty (to be filled by the user after solving the visual challenge)

Raises: APIError for generic API errors

student_login()

The Webportal.student_login() method accepts a solved Captcha object as one of its parameters.

Location: pyjiit/wrapper.py111-143

Parameters:

• username: Student username
• password: Student password
• captcha: Captcha object with the captcha field filled with the user's answer

Process: The method calls captcha.payload() to extract the necessary fields and includes them in the serialized payload sent to the /token/pretoken-check endpoint.

Sources: pyjiit/wrapper.py111-143

Sample Captcha Data

The library provides a pre-populated CAPTCHA constant in pyjiit/default.py for testing and demonstration purposes.

CAPTCHA Constant

Sample Values:

Note: This is a static sample captcha and should not be used for actual authentication. It serves as an example of the data structure and can be used for initial testing or documentation purposes.

Sources: pyjiit/default.py1-8

Integration Example

The following table shows how Captcha integrates with other pyjiit components:

Sources: pyjiit/wrapper.py6-7 pyjiit/wrapper.py111-154