WARNING: This project's code is 100% generated by AI, use at your own risk.

This document is also available in 中文

A FastAPI third-party HTTP layer over Yanshan University's unified authentication (CAS) and academic systems — the network wrapper around ysu-sdk.

• Exposes the SDK's full CAS login flow, including CAPTCHA and SMS / cpdaily MFA.
• Exposes the SDK's full academic-system surface: grades, statistics / distribution / ranking, GPA, schedule, exams, student profile, training plan, academic completion / warnings, and course evaluation.

• Stateless. The server never holds user credentials. Every request carries a Base64-encoded CAS cookie JSON (the output of CASCredential.to_json()) in the X-CAS-Credential header, and an optional X-JWXT-Session header for jwxt-domain cookies.
• Session rotation. After each request the server may return updated X-CAS-Credential / X-JWXT-Session response headers (via SessionRotationMiddleware). Clients should read and persist them to minimize CAS round-trips.
• Error pass-through. CASError / JWXTError raised by the SDK are mapped into HTTP responses with a code field (see Error model), so clients can branch on a business code rather than parse messages.
• Only evaluation writes. Like the SDK, the only endpoint that mutates server state is POST /jwxt/evaluation/submit.

Requires Python ≥ 3.12 and uv. ysu-sdk is declared as a path dependency in pyproject.toml and resolved automatically by uv:

uv sync
# or
uv pip install -e .

uv run python -m ysu_api.main

The service binds 0.0.0.0:11920 by default. Once running, open http://localhost:11920/docs for Swagger UI or http://localhost:11920/redoc for ReDoc.

For production, drive uvicorn directly:

uv run uvicorn ysu_api.main:app --host 0.0.0.0 --port 11920

The API exposes both of the SDK's login paths so callers can pick whichever fits — one-shot for CLIs, step-by-step for browser front-ends.

Submit everything (password, CAPTCHA, MFA code) in a single request. Convenient for CLIs and scripts.

curl -sX POST http://localhost:11920/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "<student id>",
    "password": "<password>",
    "captcha": "",
    "mfa_code": "<sms code>",
    "mfa_method": "cpdaily"
  }'
# → {"credential": "<base64-json>"}

If the server requires CAPTCHA and captcha is empty → 403 NEED_CAPTCHA. Call POST /auth/captcha to fetch a Base64 PNG, then retry.

If the server requires MFA and mfa_code is empty → 403 MFA_REQUIRED.

Use this when you cannot complete "ask for password → prompt for MFA → resubmit" inside a single request.

1. POST /auth/captcha             → fetch a CAPTCHA image if needed
2. POST /auth/login/step1         → submit username / password (/ captcha)
                                     - authenticated=true → full credential returned, done
                                     - needs_mfa=true     → temporary credential returned, go to 3
3. POST /auth/login/mfa/request   (header: X-CAS-Credential) → ask server to send SMS
4. POST /auth/login/mfa/submit    (header: X-CAS-Credential) → submit code, receive final credential

The returned credential string is the auth token for every academic endpoint, carried via X-CAS-Credential. You may also supply an X-JWXT-Session header (see Session rotation) to skip the CAS authorize cold path:

curl -s http://localhost:11920/jwxt/student/info \
  -H "X-CAS-Credential: $CREDENTIAL" \
  -H "X-JWXT-Session: $JWXT_SESSION"

Clients should persist both headers (e.g. browser localStorage) and update them from every response (see Session rotation below). When the credential expires, academic endpoints return 401 not authenticated — run the login flow again.

The full schema is served at /docs. The tables below list endpoints by category.

Every /jwxt/* endpoint requires the X-CAS-Credential header and optionally accepts X-JWXT-Session (see Session rotation).

grades/statistics, grades/distribution, and grades/ranking share one dispatch rule: exactly one of class_id or course_code must be provided. Passing both or neither follows the SDK and raises JWXTBusinessError / ValueError (the former maps to HTTP 422).

During a request the SDK may refresh CAS-domain cookies (e.g. happyVoyage) or jwxt-domain cookies (JSESSIONID, _WEU). To keep these updates on the client side, SessionRotationMiddleware writes the latest snapshots back into every response:

Clients must read these headers after each API call and overwrite their local copy. Supplying a stale X-JWXT-Session is safe — the server falls back to the cold path (one extra CAS authorize call), but persisting the fresh values eliminates most round-trips to cer.ysu.edu.cn.

When YSU_API_CORS_ORIGINS is configured, both headers are already listed in expose_headers so browser JS can read them.

SDK exceptions are normalized into the response shape below (see ysu_api/exc_handlers.py):

Body shape:

{"detail": "human-readable message", "code": "NEED_CAPTCHA"}

code is only present for rows in the table above. Clients should branch on code and surface detail for display.

• Treat both headers as session cookies. Anyone holding X-CAS-Credential or X-JWXT-Session can impersonate the student. Beyond TLS in transit, clients should guard them as carefully as access tokens.
• CORS is off by default. Without YSU_API_CORS_ORIGINS, CORSMiddleware is not mounted. Configure the allow-list explicitly when deploying behind a browser front-end.
• The credential header is read only when necessary. /auth/login and /auth/login/step1 ignore X-CAS-Credential, so the credential never traverses pre-login paths.