Aula

Unofficial async Python client for the Danish school platform aula.dk. The project delivers:

1. Async Python API client — programmatic access to profiles, messages, calendar, posts, and more
2. CLI — read messages, calendar, posts, presence, and widget data from the terminal
3. AI agent skill — teach Claude Code or OpenCode to query school data

Table of Contents

• Installation
• Quick Start
• Authentication
• CLI
• Configuration
• AI Agent Integration
• Project Structure
• Attribution
• License

Installation

pip install aula
# or with uv
uv add aula

Requirements: Python >= 3.14, MitID username and MitID app.

Run without installing

Use uvx to run the CLI directly from PyPI without a permanent install:

uvx aula --username johndoe messages --limit 5

Install from Source

git clone https://github.com/nickknissen/aula.git
cd aula
pip install -e .

Quick Start

import asyncio
from aula import FileTokenStorage
from aula.auth_flow import authenticate_and_create_client

async def main():
    token_storage = FileTokenStorage(".aula_tokens.json")
    async with await authenticate_and_create_client("your_mitid_username", token_storage) as client:
        profile = await client.get_profile()
        print(profile.display_name)
        for child in profile.children:
            overview = await client.get_daily_overview(child.id)

asyncio.run(main())

Key methods on AulaApiClient: get_profile(), get_daily_overview(child_id), get_message_threads(), get_messages_for_thread(thread_id), get_calendar_events(...), get_posts(...), get_groups(...), get_message_folders(...), search(...), update_presence_template(...), update_presence_status(...), get_profile_master_data(...), get_secure_documents(...), get_consent_responses(...), get_auto_reply(), get_vacation_registrations(...), get_notification_settings(), keep_alive(). See src/aula/api_client.py for the full list.

Widget API (Namespace)

Widget integrations are available via the namespaced widgets client on AulaApiClient:

tasks = await client.widgets.get_mu_tasks(
    widget_id="0030",  # WIDGET_MIN_UDDANNELSE_TASKS
    child_filter=["12345"],
    institution_filter=["5678"],
    week="2026-W8",
    session_uuid="guardian-user-id",
)

Use the client.widgets.* namespace for widget calls (for example: get_mu_tasks, get_ugeplan, get_easyiq_weekplan, get_meebook_weekplan, get_momo_courses, get_library_status).

Legacy direct widget methods on AulaApiClient are deprecated and will be removed in a future release. Migrate to client.widgets.<method>(...).

Authentication

What You Need

• MitID username — your MitID username (not your Aula username). Find it at mitid.dk.
• A MitID authenticator — either the MitID app on your phone, or a MitID kodeviser (code display device) plus your MitID password.

Authentication Methods

Pick with --auth-method (or the AULA_AUTH_METHOD env var):

MitID chip and audio code readers (kodeoplæser) are not supported. If your account offers one, it's listed in a warning at -v and the login falls back to whatever else you have.

First Login

On first run you'll be prompted to approve the login. Tokens are saved to the storage file and reused on subsequent runs — no authenticator interaction needed until they expire.

For the kodeviser method you can skip the prompts:

export AULA_MITID_PASSWORD='...'      # or --password
aula --auth-method token --token-code 123456 messages

The kodeviser code rotates, so --token-code is only useful for a single run. The password is never written to the config file; supply it per-run or via the environment.

Token Security

Tokens provide full access to your Aula account — treat them like passwords and never commit token files to version control.

How It Works

For a detailed breakdown of the authentication flow (OAuth + SAML + MitID), session cookies, and how this library differs from the browser login, see docs/aula-authentication.md.

CLI

Install as a standalone tool:

# with uv (recommended)
uv tool install aula

# or with pip
pip install aula

Then run:

aula --username <your_mitid_username> [COMMAND]

The username can also be set via the AULA_MITID_USERNAME environment variable or a config file.

Core

Messages

Calendar

Presence

Content

Widgets

Global flags

JSON output

All commands support --output json for machine-readable output:

aula --output json messages --unread
aula --output json daily-summary --child "Emma"
aula --output json calendar --start-date 2026-03-10

Examples

aula --username johndoe messages --limit 5
# or without installing
uvx aula --username johndoe messages --limit 5

Configuration

~/.config/aula/config.json:

{
  "mitid_username": "your_mitid_username"
}

The username is saved automatically on first login. CLI flags and environment variables take precedence over the config file.

AI Agent Integration

The CLI is designed to work with AI coding agents like Claude Code and OpenCode. The agent-setup command installs a skill that teaches agents how to query Aula for school data.

# Install for the current project
aula agent-setup

# Install globally (all projects)
aula agent-setup --global

This creates a SKILL.md following the Agent Skills open standard under .claude/skills/aula/, which is read by both Claude Code and OpenCode. Once installed, agents can invoke /aula or automatically use the CLI when you ask about school data.

Project Structure

src/aula/
  api_client.py             # Async API client (main entry point)
  cli.py                    # Click CLI commands
  auth_flow.py              # High-level auth orchestration
  config.py                 # CLI config (~/.config/aula/config.json)
  token_storage.py          # Token persistence (ABC + file impl)
  auth/                     # MitID authentication
    mitid_client.py         # 7-step OAuth+SAML+MitID flow
    browser_client.py       # Low-level MitID protocol (QR, OTP, SRP)
    srp.py                  # Secure Remote Password with AES-GCM
  models/                   # API data models (one file per model)
  utils/                    # HTML helpers, table rendering, downloads
tests/                      # Mirrors src/aula/ structure

Attribution

• Aula API usage was inspired by the scaarup/aula Home Assistant integration.
• MitID authentication was inspired by the Hundter/MitID-BrowserClient project.
• EasyIQ widget integration (weekplan and homework) was inspired by the esbenwiberg/easyiq Home Assistant integration.
• Additional API endpoints were discovered via the eisbaw/aulalibre Rust client, which reverse-engineered the Aula Android app.

License

MIT