# Untis Access

> Access WebUntis accounts and APIs for debugging, research, or automation. Use when the user wants to log into a WebUntis tenant, read inbox messages, fetch guardian/dependent timetables, inspect homework or exams, compare WebUntis library implementations, or validate auth flows such as JSON-RPC login, JWT minting, or shared-secret OTP.

- Skill: `lefant/untis-access` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add lefant/untis-access`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lefant/untis-access/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: lefant (https://skillmd.com/u/lefant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lefant/untis-access

---


# Untis Access

Use this skill for direct WebUntis access work, especially when repo wrappers are incomplete and the fastest path is to prove the live API behavior.

## Scope

Use this skill for:
- reading WebUntis inbox messages or message details
- reading guardian/dependent timetable data
- investigating homework or exam availability
- comparing local WebUntis-related repos and auth models
- building or running proof scripts against a live tenant

Do not use this skill for:
- generic browser automation if direct HTTP access already works
- non-WebUntis school systems
- UI polish or frontend work unrelated to WebUntis data access

## Default workflow

1. Read `references/research/2026-04-16_webuntis-message-access.md` for the proven tenant flow and repo overview.
2. Read `references/auth-and-env.md` and confirm the credential file convention.
3. Check config completeness before running scripts: `WEBUNTIS_USERNAME`, `WEBUNTIS_PASSWORD`, `WEBUNTIS_HOST`, and `WEBUNTIS_SCHOOL`. If host or school is missing, consult the user's local setup notes before proceeding.
4. Start from the bundled script closest to the task:
   - `scripts/read-latest-message.py` for inbox access
   - `scripts/read-timetable.py` for guardian/dependent timetable access
5. Only branch into repo comparison or alternate auth when the default scripts do not cover the target surface.
6. Validate by running the script and confirming the response is real JSON data, not the SPA shell.

## Defaults

- default credential source: `~/.env.webuntis`
- default tenant config: provide `WEBUNTIS_HOST` and `WEBUNTIS_SCHOOL` locally; do not commit tenant-specific values into the skill
- default auth path: JSON-RPC `authenticate` → `/WebUntis/api/token/new` → `/WebUntis/api/...`
- default implementation strategy: direct HTTP proof first, repo patch second
- fallback auth path: shared-secret TOTP only when you intentionally need the `jsonrpc_intern.do` flow

## Gotchas

- On this tenant, the working authenticated base is `/WebUntis/api/...`, not bare `/api/...`.
- Guardian accounts do not work with old timetable JSON-RPC element type assumptions; resolve dependents via `timetable/menu` first.
- JWT lifetime is short. Mint a fresh token every run.
- `JSESSIONID` server-side lifetime is unclear. For unattended jobs, fresh login per run is safer than session reuse.
- `SchoolUtils/WebUntis` only covers inbox preview data; full message detail needs direct REST calls or repo patching.
- `kaiser-jan/scriptable-untis` is a good timetable reference, but it is not obviously guardian-aware out of the box.

## Validation

Before finishing:
- run the relevant bundled script
- verify the response contains expected data for the target surface
- verify the response is JSON and not HTML
- if a route fails, compare it against the proven endpoints in `references/research/2026-04-16_webuntis-message-access.md`

## Read next

- `references/auth-and-env.md` when setting up credentials or documenting auth assumptions; do not commit real usernames, tenant values, or personal timetable data into the skill
- `references/research/2026-04-16_webuntis-message-access.md` when comparing repos, auth models, or endpoint choices
- `references/proofs/2026-04-16_webuntis-message-access_README.md` when you need the exact proved message and timetable flows

## Available scripts

- `scripts/read-latest-message.py` — log in, mint JWT, list inbox, fetch newest full message
- `scripts/read-timetable.py` — log in, resolve dependent student, print weekly timetable, optionally print teacher code mappings