aula 0.5.0

Python API wrapper for Aula.

Aula

Async Python client for the Danish school platform aula.dk.

• Fetch calendar events, messages, posts, and daily overviews
• Authenticate via Denmark's MitID national identity system
• Token caching — MitID app approval only needed on first login
• Full async API client (AulaApiClient) and a CLI included

Installation

pip install aula
# or with uv
uv add aula

Requirements: Python >= 3.10, 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(...). 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
    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.
• MitID app — installed and set up on your phone.

First Login

On first run you'll be prompted to approve the login in your MitID app. You may need to scan a QR code or enter an OTP shown in the terminal. Tokens are saved to the storage file and reused on subsequent runs — no app interaction needed until they expire.

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

aula --username <your_mitid_username> [COMMAND]

The username can also be set via the AULA_MITID_USERNAME environment variable or a config file (~/.config/aula/config.json).

Command	Description
login	Verify credentials
profile	Show profile and children
overview	Daily overview for all children
messages	Recent message threads
calendar	Calendar events
posts	Posts and announcements

Example:

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

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.

License

MIT