mud_server.admin_gradio.api.auth

Authentication API client for MUD Server.

This module handles all authentication-related API operations: - User login with password authentication - New user registration - User logout and session cleanup

All functions follow a consistent pattern:

• Validate input using validators module

• Make API request using BaseAPIClient

• Return standardized response dictionaries

Response Format:

All functions return dictionaries with: {

“success”: bool, # Whether operation succeeded “message”: str, # User-facing message “data”: dict | None, # Additional data (session_id, role, etc.) “error”: str | None, # Error details if failed

}

Attributes

logger

Classes

AuthAPIClient

API client for authentication operations.

Module Contents

mud_server.admin_gradio.api.auth.logger

class mud_server.admin_gradio.api.auth.AuthAPIClient(server_url=None)

Bases: mud_server.admin_gradio.api.base.BaseAPIClient

API client for authentication operations.

This client handles login, registration, and logout operations, providing clean separation between API logic and UI concerns.

Example

>>> client = AuthAPIClient()
>>> result = client.login("alice", "password123")
>>> if result["success"]:
...     print(f"Logged in: {result['data']['session_id']}")

Initialize the base API client.

Parameters:

server_url (str | None) – Optional server URL override. If not provided, uses MUD_SERVER_URL environment variable or defaults to http://localhost:8000

login(username, password)

Authenticate user and create session.

Validates credentials, sends login request to backend, and returns session data on success.

Parameters:

• username (str) – Username to login with

• password (str) – Plain text password

Returns:

{

“success”: bool, “message”: str, “data”: {

”session_id”: str, “username”: str, “role”: str,

} | None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

>>> client = AuthAPIClient()
>>> result = client.login("alice", "password123")
>>> result["success"]
True
>>> result["data"]["role"]
'player'

register(username, password, password_confirm)

Register a new user account.

Validates input, sends registration request to backend API, and returns status message indicating success or failure.

Parameters:

• username (str) – Desired username for new account

• password (str) – Plain text password for new account

• password_confirm (str) – Password confirmation (must match password)

Returns:

{

“success”: bool, “message”: str, “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

>>> client = AuthAPIClient()
>>> result = client.register("bob", "password123", "password123")
>>> result["success"]
True
>>> "You can now login" in result["message"]
True

logout(session_id)

Logout user and clean up session.

Sends logout request to backend API and returns confirmation.

Parameters:

session_id (str | None) – Session ID to logout (can be None if not logged in)

Returns:

{

“success”: bool, “message”: str, “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

>>> client = AuthAPIClient()
>>> result = client.logout("abc123")
>>> result["success"]
True
>>> result["message"]
'You have been logged out.'