# Stundentakt learning tools > Stundentakt is a toolbox for lessons: teachers build media from blocks, assign them to classes, pupils answer under a pseudonym. A learning tool is an external web page that Stundentakt frames as a block; it signs its person in with OAuth 2 (authorization code with PKCE S256, public client, `prompt=none`), reads its task and the whole medium, saves drafts, hands in results, keeps per-person data (records), reports progress as xAPI-shaped events and reads the subscription — all through the tools API at https://stundentakt.net/api/v1/tools. The documentation is written in German and complete enough to build a tool without further questions: start with the overview and the quickstart (one HTML file, no library). Every refusal is `{message, reason}`; decide by `reason`. Pupils are only pseudonyms; guests get no token. People start at https://stundentakt.net/developers. ## I build a learning tool · Ich baue ein Werkzeug - [Overview](https://stundentakt.net/docs/developers/overview.md): What Stundentakt does for a tool, the terms, what goes where, roles and modes, privacy. - [Quickstart](https://stundentakt.net/docs/developers/quickstart.md): From an empty folder to a docked tool: register it, one complete HTML page without a library, test it. - [Recipes](https://stundentakt.net/docs/developers/recipes.md): Ready snippets: saving and sharing records, reporting progress, author mode with drafts, conflicts, signing out, errors, frame or window, my assignments, opening a pasted link, display per block. ## I teach or edit and want to embed a tool · Ich bin Lehrer:in oder Redaktion und will ein Werkzeug einbinden - [Learning tools for teachers](https://stundentakt.net/docs/teachers/tools.md): Register a tool, put it into a medium, assign it, what pupils see and the evaluation. ## Reference · Referenz - [Reference](https://stundentakt.net/docs/developers/reference.md): The binding contract: launch, OAuth, every route and field, error reasons, CORS, limits and privacy. - [OpenAPI 3.1](https://stundentakt.net/api/v1/tools/openapi.json): every route under https://stundentakt.net/api/v1/tools with scopes, request and response schemas and the error body with every `reason` - Authorization endpoint `https://stundentakt.net/oauth/authorize`: `response_type=code`, `code_challenge_method=S256`, scopes `tools:read` and `tools:write`, `prompt=none` - Token endpoint `https://stundentakt.net/oauth/token`: exchanges the code with `code_verifier`, rotates refresh tokens ## Optional - [Full text](https://stundentakt.net/llms-full.txt): this index followed by every file above - [For developers](https://stundentakt.net/developers): the same documentation as a page for people - MCP server `https://stundentakt.net/mcp`: Streamable HTTP for a teacher's own AI assistant (OAuth with dynamic client registration); not for learning tools --- # Lernwerkzeuge in Stundentakt – Überblick Ein **Lernwerkzeug** ist eine Webseite eines fremden Anbieters (Übungen, Simulationen, Programmierumgebungen, Vokabeltrainer …), die Stundentakt als Baustein in den Unterricht einbindet. Das Werkzeug läuft auf seiner eigenen Adresse; Stundentakt rahmt es ein oder öffnet es in einem eigenen Fenster und führt es nie selbst aus. Gesprochen wird über HTTPS und JSON: Anmeldung per OAuth 2, danach die Werkzeug-API unter `https://stundentakt.eu/api/v1/tools`. Die Dateien dieser Doku: | Datei | für wen | |---|---| | `/docs/developers/overview.md` (diese) | alle: Begriffe, was wohin gehört, Rollen, Datenschutz | | `/docs/developers/quickstart.md` | Entwickler:in: vom leeren Ordner zum angedockten Werkzeug, mit kopierbarer Seite | | `/docs/developers/recipes.md` | Entwickler:in: fertige Ausschnitte für Records, Ereignisse, Autorenmodus, Meine Kurse, Links, Anzeige, Fehler | | `/docs/teachers/tools.md` | Lehrer:in und Redaktion: Werkzeug eintragen, einbauen, zuweisen, auswerten | | `/docs/developers/reference.md` | Entwickler:in: der verbindliche Vertrag mit allen Routen, Feldern, Fehlern und Grenzen | Maschinenlesbar: `/llms.txt`, `/llms-full.txt` (alle Dateien hintereinander) und `/api/v1/tools/openapi.json` (OpenAPI 3.1). ## Was Stundentakt einem Werkzeug abnimmt - **Konten und Anmeldung:** Lehrer:innen, Schüler:innen, Klassen, Schulen; Anmeldung mit Passwort, beste.schule, Klassencode oder Anmeldekarte. Das Werkzeug bekommt per OAuth ein Token für genau eine Person und braucht keine eigene Nutzerverwaltung. - **Unterricht:** wer in welcher Klasse ist, welche Aufgabe wann offen ist (Fenster, Frist, „Nur ansehen“), wer die Antworten einer Klasse lesen darf. - **Speicher:** Zwischenstand und Abgabe je Person und Aufgabe, eigene Daten der Person (Records) mit Freigabe an Klasse, Schule oder alle, Dateien einer Abgabe. - **Auswertung:** Die Lehrer:in sieht Abgaben, Punkte und die gemeldeten Ereignisse ihrer Klasse in Stundentakt; das Werkzeug muss dafür keine eigene Lehrer:innen-Ansicht bauen (kann aber den Modus `review` anbieten). - **Abo:** Welcher Plan die Person trägt, steht in `GET me`; ein Werkzeug rechnet nichts selbst ab. ## Begriffe | Begriff | Bedeutung für ein Werkzeug | |---|---| | **Person** | wer das Token hält: eine Lehrer:in (`kind: user`) oder eine Schüler:in (`kind: member`). Erkennbar nur an ihrem Pseudonym bzw. Anzeigenamen (`alias`), nie an Name, E-Mail oder einer Nummer. | | **Klasse** | eine Gruppe aus Lehrer:innen und Schüler:innen. Das Werkzeug sieht sie nie direkt, nur über eine Zuweisung. | | **Medium** | ein Dokument aus Bausteinen (Arbeitsblatt, Kurs, Tafel, Lernwerkzeug …), gebaut von einer Lehrer:in. Adressiert per ULID (`document`). | | **Baustein** | ein Teil eines Mediums. Ein Baustein vom Typ `tool` verweist auf genau ein eingetragenes Werkzeug und trägt dessen Aufgabe: `title`, `task` (JSON des Werkzeugs) und `hidden` (JSON, das nur die Autor:in und das Werkzeug in ihrer Hand sehen, z. B. Tests). Adressiert per ULID (`block`). | | **Zuweisung** | ein Medium, freigegeben für eine Klasse, mit Fenster und Frist. Eine Zuweisung ohne Klasse entsteht, wenn ein Medium per Link oder öffentlich geteilt wird. Adressiert per ULID (`assignment`). | | **Antwort** | was eine Person zu einem Baustein einer Zuweisung abgibt: `done`, `score`, `max_score`, `state`, Dateien. Je Person und Baustein gibt es eine; eine neue Abgabe ersetzt die alte. Daneben ein **Zwischenstand** (`draft.state`), den eine Abgabe löscht. | | **Record** | freie Daten, die einer Person in einem Werkzeug gehören (eigene Programme, Vokabellisten, Einstellungen), in einer **Datenart** (`collection`), die das Werkzeug frei benennt. Privat, bis die Person sie freigibt. | | **Ereignis** | eine Lernspur im Stil einer xAPI-Aussage: Verb (`run`, `error`, `step` …), optional Objekt, Ergebnis, Zeit. Mit Zuweisung zählt es in der Auswertung der Klasse, ohne Zuweisung gehört es nur Person und Werkzeug. | | **Abo** | der Plan (`free`, `pro`, `premium`) des Teams, das die Person trägt, mit Schaltern und Speichergrenze; gelesen über `GET me`. | | **ULID** | jede Kennung nach außen: 26 Zeichen Crockford-Base32 (Stundentakt schreibt sie klein). Interne Nummern gibt die API nie heraus. | ## Faustregel: was wohin gehört | Die Daten … | gehören in … | Route | |---|---|---| | beschreiben eine Aufgabe, die eine Lehrer:in stellt | den Baustein (`task`, `hidden`, `display`) | `PUT blocks/{block}` (Modus `author`) | | sind die Arbeit einer Person an dieser Aufgabe, noch nicht fertig | den Zwischenstand | `PUT assignments/{a}/blocks/{b}/draft` | | sind ihr Ergebnis, das die Lehrer:in sehen soll | die Antwort | `POST assignments/{a}/blocks/{b}/response` | | gehören nur der Person, unabhängig von einer Aufgabe | einen Record | `POST collections/{c}/records` | | beschreiben, was beim Lernen passiert ist (ausgeführt, Fehler, Schritt) | ein Ereignis | `POST assignments/{a}/events` bzw. `POST events` | | sind ein unveröffentlichter Entwurf einer Aufgabe | einen privaten Record (z. B. Datenart `drafts`), veröffentlicht wird per `PUT blocks/{block}` | siehe `/docs/developers/recipes.md` | Ein Werkzeug legt keine Tabellen an und speichert nichts ohne Person: Stundentakt kennt nur diese Orte. ## Rollen und Modi Stundentakt startet das Werkzeug mit seiner Start-Adresse und hängt Parameter an: ``` https://werkzeug.example/start?mode=learn&assignment=&block=&lang=de ``` | Modus | wer | Parameter | was das Werkzeug tut | |---|---|---|---| | `learn` | eine Schüler:in der Klasse, eine mitmachende Lehrer:in, auf dem Link auch eine angemeldete Person wie ein Gast | `assignment`, `block` | Aufgabe zeigen, Zwischenstand speichern, abgeben, Ereignisse melden | | `review` | die Lehrer:in der Klasse | `assignment`, `block`, `response` | eine abgegebene Antwort nur lesend zeigen | | `author` | die Lehrer:in, die das Medium baut | `document`, `block` | Titel, Aufgabe und versteckten Teil schreiben | `lang` ist immer `de` oder `en`. Die Rolle der Person in einer Zuweisung steht in `me.role` der Antwort auf `GET assignments/{a}`: `teacher` (leitet die Klasse), `student` oder `guest` (nimmt auf einem Link teil). Anzeige: `inline` (Rahmen in der Seite von Stundentakt) oder `full` (Karte, die das Werkzeug in einem eigenen Fenster öffnet). Der Eintrag gibt sie vor, jeder Baustein kann sie für sich überschreiben (`payload.display`). Beides ist derselbe Ablauf; Unterschiede in `/docs/developers/recipes.md`, „Rahmen oder eigenes Fenster“. ## Datenschutz - **Pseudonym:** Eine Schüler:in heißt für das Werkzeug nur nach ihrem Pseudonym (`alias`), eine Lehrer:in nach ihrem Anzeigenamen („J. Muster“). Nie ein echter Name einer Schüler:in, nie eine E-Mail, nie eine interne Nummer. Ein Werkzeug fragt auch selbst nicht danach. - **Gäste** (ohne Konto über einen geteilten Link) sind für Werkzeuge nicht angemeldet: kein Token, keine Records. `/oauth/authorize` antwortet `error=access_denied&reason=guest_not_supported`; das Werkzeug speichert für sie höchstens auf dem Gerät. - **Lösungen:** Lösungen anderer Bausteine des Mediums sieht ein Werkzeug erst, wenn die App sie der Person zeigt (nach der Frist; die Lehrer:in der Klasse immer). Eigene Lösungen darf das Werkzeug in `hidden` oder bei sich halten; Stundentakt prüft keine Antwort nach. - **Kein Token ist mehr als die Person:** Ein Token gilt für ein Werkzeug und eine Person und erreicht nur die Werkzeug-API. Werkzeug A liest nie die Records von Werkzeug B. - **Löschen:** Wer Konto, Mitglied, Klasse oder den Werkzeug-Eintrag löscht, löscht Zwischenstände, Antworten, Records und Ereignisse mit. - Arbeitsdaten (`state`, Records) erscheinen in keinem Export, keiner Auswertung und erreichen nie eine KI. --- # Schnellstart: ein Lernwerkzeug andocken Vom leeren Ordner zu einem Werkzeug, das in Stundentakt startet, die Person anmeldet, seine Aufgabe lädt, einen Zwischenstand speichert und abgibt. Eine einzige HTML-Datei, kein Server-Code, keine Bibliothek. Begriffe in `/docs/developers/overview.md`, alle Einzelheiten in `/docs/developers/reference.md`. Im Folgenden steht `https://stundentakt.eu` für die Stundentakt-Instanz; bei einer anderen Instanz deren Adresse. ## 1 Was das Werkzeug braucht - Eine Seite unter einer festen Adresse, z. B. `https://werkzeug.example/` (zum Ausprobieren `http://localhost:8080/`, siehe Abschnitt 4). Diese Adresse ist zugleich **Start-Adresse** und **Rücksprungadresse** für OAuth. - Die Seite muss sich von `https://stundentakt.eu` einrahmen lassen: kein `X-Frame-Options: DENY`, und wenn sie eine Content Security Policy setzt, nennt `frame-ancestors` Stundentakt. - Sie ruft die API mit `fetch` ohne Cookies auf. Stundentakt erlaubt CORS genau für die Origin der Start-Adresse (Schema, Host, Port). ## 2 Eintragen 1. In Stundentakt als Lehrer:in anmelden, im Profilmenü **Lernwerkzeuge** öffnen (`/tools`), **Lernwerkzeug hinzufügen**. 2. Ausfüllen: - **Name:** z. B. „Mein Werkzeug“. - **Startadresse** (`launch_url`): `https://werkzeug.example/` – `https://` Pflicht, `http://` nur für `localhost`, `127.0.0.1`, `[::1]`; ohne `#`, ohne Benutzer:in/Passwort. - **Rücksprungadressen** (`redirect_uris`), eine je Zeile, bis zu 10: hier dieselbe Adresse `https://werkzeug.example/`. Der Wert von `redirect_uri` im Code muss **genau** einer Zeile entsprechen. - **Anzeige:** „In der Seite“ (`inline`, Rahmen) oder „In eigenem Tab“ (`full`). 3. **Lernwerkzeug speichern.** In der Liste steht unter der Startadresse die **Client-ID** (`client_id`, eine UUID). Sie ist öffentlich; ein Secret gibt es nicht. Ein Werkzeug gehört der Lehrer:in, die es einträgt, und steht nur ihr zur Verfügung; Werkzeuge für alle trägt der Betreiber ein (`/docs/teachers/tools.md`). ## 3 Die Seite Als `index.html` speichern, `STUNDENTAKT` und `CLIENT_ID` oben anpassen. Die Seite kann den Modus `learn`: 1. Start-Parameter (`mode`, `assignment`, `block`, `lang`) in `sessionStorage` merken – der OAuth-Rücksprung kommt ohne sie zurück. 2. PKCE erzeugen (`code_verifier` und `code_challenge` mit SHA-256) und still anmelden: Navigation zu `/oauth/authorize?…&prompt=none`. Stundentakt springt mit `?code=…&state=…` zurück (oder mit `?error=login_required`, wenn niemand angemeldet ist: dann ein Knopf, der ohne `prompt` anmeldet). 3. Code gegen Tokens tauschen (`POST /oauth/token`), Tokens in `sessionStorage`. 4. `GET me` (wer), `GET assignments/{a}` (Aufgabe), `GET …/draft` (Zwischenstand und frühere Abgabe). 5. Speichern mit `PUT …/draft`, Abgeben mit `POST …/response`. 6. Bei `token_expired` mit dem Erneuerungstoken erneuern; bei `token_revoked`/`token_invalid` still neu anmelden. 7. Seine Höhe per `postMessage` an den Rahmen melden. ```html Mein Werkzeug

Lädt …

``` Was die Aufgabe enthält, bestimmt das Werkzeug selbst: `task` ist beliebiges JSON. Dieses Beispiel erwartet `{"text": "…"}` und speichert seinen Stand als `{"text": "…"}`. Wie eine Lehrer:in die Aufgabe im Werkzeug schreibt (Modus `author`), steht in `/docs/developers/recipes.md`. ## 4 Lokal testen 1. Seite ausliefern, etwa mit `python3 -m http.server 8080` im Ordner der Datei. Ein Server, der jede Datei mit `X-Frame-Options` versieht, passt nicht. 2. Eintrag wie in Abschnitt 2 mit Start- und Rücksprungadresse `http://localhost:8080/`. Browser behandeln `http://localhost` als sichere Herkunft, darum lädt die Seite auch im Rahmen einer `https://`-Seite. 3. Ein Medium bauen: **Neues Medium → Lernwerkzeug** (oder in einem beliebigen Medium den Baustein „Lernwerkzeug“ einfügen), das Werkzeug wählen, Titel eintragen. Die Aufgabe (`task`) schreibt das Werkzeug im Modus `author`; für diesen Test reicht der Titel. 4. Das Medium der eigenen Klasse zuweisen. 5. Testen: - als Lehrer:in in der Klasse (sie macht dort mit wie eine Schüler:in, `me.role` ist `teacher`), oder - als Schüler:in: in einem zweiten Browserprofil über den Klassencode bzw. die Anmeldekarte anmelden und das Medium öffnen. 6. Prüfen: Name im Kopf (`Angemeldet als …`), Text schreiben, **Zwischenstand speichern**, Seite neu laden (der Text ist wieder da), **Abgeben**. Die Lehrer:in sieht die Abgabe in der Auswertung der Zuweisung. Fehlerbilder: | Zeigt | Ursache | |---|---| | leerer Rahmen | die Seite verbietet das Einrahmen (`X-Frame-Options`, `frame-ancestors`) | | `401 invalid_client` beim Anmelden, kein Rücksprung | `redirect_uri` steht nicht genau so am Eintrag | | CORS-Fehler in der Konsole | die Seite läuft nicht auf der Origin der Start-Adresse (anderer Port, `127.0.0.1` statt `localhost`) | | `Bitte das Werkzeug aus Stundentakt heraus öffnen.` | Seite direkt aufgerufen, ohne Start-Parameter | | `Fehler: forbidden` | die Person nimmt an dieser Zuweisung nicht teil | | `Fehler: not_found` | der Baustein gehört zu einem anderen Werkzeug-Eintrag | ## 5 Wie es weitergeht - Eigene Daten der Person, Ereignisse, Autorenmodus, Konflikte, Abmelden: `/docs/developers/recipes.md`. - Alle Felder, Fehlercodes und Grenzen: `/docs/developers/reference.md` bzw. `/api/v1/tools/openapi.json`. --- # Rezepte Fertige Ausschnitte für häufige Aufgaben eines Lernwerkzeugs. Sie setzen die Seite aus `/docs/developers/quickstart.md` voraus, vor allem diese Teile: - `STUNDENTAKT` – die Adresse der Instanz, z. B. `https://stundentakt.eu`. - `launch` – die gemerkten Start-Parameter (`mode`, `assignment`, `block`, `document`, `response`, `lang`). - `api(method, path, body)` – ruft `STUNDENTAKT + '/api/v1/tools' + path` mit dem Zugriffstoken auf, erneuert bei `token_expired`, meldet bei `token_revoked`/`token_invalid` still neu an, wartet bei `too_many_requests` und `maintenance` `Retry-After` Sekunden. Es gibt das JSON zurück (bei `204` `null`) und wirft sonst einen Fehler mit `reason`, `status` und dem ganzen Körper in `body`. Alle Felder und Grenzen stehen in `/docs/developers/reference.md`. ## Eigene Programme speichern und teilen (Records) Was einer Person gehört und an keiner Aufgabe hängt – eigene Programme, Vokabellisten, Einstellungen – ist ein **Record**. Die Datenart (`collection`) benennt das Werkzeug selbst (`[a-z0-9_-]`, 1–64 Zeichen); `data` ist beliebiges JSON bis 64 KB, `schema` die eigene Formatnummer. ```js // Anlegen: privat, solange die Person nichts anderes wählt. const program = await api('POST', '/collections/programs/records', { data: { name: 'Ampel', code: 'rot(); warte(2); gruen();' }, schema: 1, }); // Die eigenen, zuletzt geänderte zuerst (Seiten zu höchstens 100). const mine = await api('GET', '/collections/programs/records?sort=-updated&per_page=50&page=1'); // → { items: [ { id, collection, data, schema, visibility, created_at, updated_at, owner }, … ], page, per_page, total } // Ändern: updated_at so mitschicken, wie zuletzt gelesen (sonst 409, siehe „Konflikte“). const renamed = await api('PATCH', '/collections/programs/records/' + program.id, { data: { ...program.data, name: 'Ampel 2' }, updated_at: program.updated_at, }); // Teilen: group = wer mit ihr eine aktive Klasse teilt, team = ihre Schule, public = jede:r mit der ULID. const shared = await api('PATCH', '/collections/programs/records/' + program.id, { visibility: 'group', updated_at: renamed.updated_at, }); // Was andere mit der Person teilen (nur lesen; owner.alias ist Pseudonym bzw. Anzeigename). const fromOthers = await api('GET', '/collections/programs/records?scope=shared'); // Löschen. await api('DELETE', '/collections/programs/records/' + program.id); ``` Ein öffentlicher Record (`visibility: 'public'`) lässt sich ohne Token lesen, etwa für einen Teilen-Link des Werkzeugs. Die Antwort trägt CORS-Kopfzeilen nur für die Origin des Werkzeugs; eine fremde Seite liest ihn über ihren eigenen Server. ```js const response = await fetch(STUNDENTAKT + '/api/v1/tools/records/' + id, { credentials: 'omit' }); const record = response.ok ? await response.json() : null; // 404 für alles, was nicht öffentlich ist ``` Speicher: `GET me` nennt unter `entitlements.records` die Grenze des Teams (`limit_bytes`), den eigenen Verbrauch (`own_bytes`) und die Grenze je Record (`record_max_bytes`). Ist das Team voll, antwortet das Schreiben `413 quota_exceeded`; eine Schüler:in ohne aktive Klasse hat keinen Speicher (`403 no_storage`). ## Fortschritt melden (Ereignisse) Ereignisse folgen der Form einer xAPI-Aussage (Person, Verb, Objekt, Ergebnis, Zeit); Person und Werkzeug nimmt Stundentakt immer aus dem Token. Bis zu 100 je Aufruf, ganz oder gar nicht gespeichert, Antwort `201 {recorded}`. **Im Unterricht** (es gibt `launch.assignment`): Mit `block` zählen sie in der Auswertung der Klasse („Vom Werkzeug gemeldet“: je Verb und Code „x von y“ Schüler:innen, bei `run` die Läufe vor der Abgabe). ```js await api('POST', '/assignments/' + launch.assignment + '/events', { events: [ { block: launch.block, verb: 'run', result: { success: false, duration: 'PT2.5S' } }, { block: launch.block, verb: 'error', code: 'err.syntax.indent' }, { block: launch.block, verb: 'step', result: { success: true, score: 0.5 } }, { block: launch.block, verb: 'submit', result: { success: true, score: { raw: 8, min: 0, max: 10 } } }, ], }); ``` **Ohne Unterricht** (das Werkzeug wird frei benutzt): kein `block`; als Objekt nur ein eigener Record. ```js await api('POST', '/events', { events: [{ verb: 'step', object: { type: 'record', id: program.id }, result: { success: true, duration: 4200 } }], }); ``` Empfohlene Verben: `run` (ausgeführt), `error` (mit `code`), `step` (Schritt geschafft), `submit` (abgegeben), `reset` (neu begonnen); andere Wörter bis 40 Zeichen sind erlaubt. `result.score` ist eine Zahl von 0 bis 1 oder `{raw, min, max, scaled}`, `duration` eine ISO-8601-Dauer oder Millisekunden. Offline gesammelte Ereignisse mit `timestamp` (ISO 8601 mit Zone) binnen 24 Stunden nachreichen; ältere Zeiten setzt Stundentakt auf „vor 24 Stunden“. ```js // Puffern und gebündelt senden. const queue = []; const track = (event) => queue.push({ ...event, timestamp: new Date().toISOString() }); async function flush() { while (queue.length) { const batch = queue.slice(0, 100); await api('POST', '/assignments/' + launch.assignment + '/events', { events: batch }); queue.splice(0, batch.length); } } setInterval(() => flush().catch(() => {}), 10000); ``` ## Autorenmodus mit Entwurf Im Modus `author` (Start mit `?mode=author&document=…&block=…`) schreibt die Lehrer:in die Aufgabe im Werkzeug. `PUT blocks/{block}` ist **veröffentlichen**: Die Klasse sieht die Änderung sofort. Stundentakt hat bewusst keinen eigenen Entwurfsplatz je Baustein; einen Entwurf, den nur die Autorin sieht, hält das Werkzeug als privaten Record (hier Datenart `drafts`) und veröffentlicht ihn auf Knopfdruck. ```js // Aufgabe lesen: blocks enthält die Bausteine dieses Werkzeugs im Medium, mit hidden für die Autorin. const { document: medium, blocks } = await api('GET', '/documents/' + launch.document); const block = blocks.find((b) => b.ulid === launch.block); // block = { ulid, type: 'tool', payload: { tool, title, task }, updated_at, hidden } // Eigenen Entwurf zu diesem Baustein suchen. const list = await api('GET', '/collections/drafts/records?per_page=100'); let draft = list.items.find((record) => record.data.block === block.ulid) ?? null; // Beim Tippen speichern (privat, unsichtbar für die Klasse). async function saveDraft(title, task, hidden) { const data = { block: block.ulid, based_on: draft?.data.based_on ?? block.updated_at, title, task, hidden }; draft = draft ? await api('PATCH', '/collections/drafts/records/' + draft.id, { data, updated_at: draft.updated_at }) : await api('POST', '/collections/drafts/records', { data }); } // Veröffentlichen: nur, wenn die Aufgabe seit based_on niemand geändert hat. async function publish() { const { title, task, hidden, based_on } = draft.data; try { const result = await api('PUT', '/blocks/' + block.ulid, { title, task, hidden, updated_at: based_on }); await api('DELETE', '/collections/drafts/records/' + draft.id); draft = null; Object.assign(block, result.block); return result; // { complete, incomplete, block } } catch (error) { if (error.reason !== 'conflict') throw error; // Jemand hat die Aufgabe inzwischen geändert: error.body.block ist der aktuelle Stand. // Zusammenführen oder der Autorin beide Fassungen zeigen, dann mit dessen updated_at erneut veröffentlichen. return { conflict: error.body.block }; } } ``` - Was der Körper von `PUT blocks/{block}` weglässt, bleibt; `task` und `hidden` je höchstens 64 KB. - `complete: false` nimmt den ganzen Baustein aus dem Unterricht, bis er fertig ist (die Klasse sieht ihn nicht); das ist kein Entwurf neben einer veröffentlichten Fassung. - `hidden` (Tests, Musterlösung) sieht nur, wer den Baustein ändern darf, und das Werkzeug in ihrer Hand. ## Konflikte (409) Zwei Stellen schützen vor stillem Überschreiben, beide mit `updated_at` als Vorbedingung: | Route | `updated_at` | Vergleich | aktueller Stand in | |---|---|---|---| | `PUT blocks/{block}` | freiwillig (ohne: der letzte Aufruf gewinnt) | auf die Sekunde | `body.block` | | `PATCH collections/{c}/records/{id}` | Pflicht | auf die Mikrosekunde | `body.record` | ```js async function patchRecord(collection, record, change, merge) { try { return await api('PATCH', `/collections/${collection}/records/${record.id}`, { ...change, updated_at: record.updated_at }); } catch (error) { if (error.reason !== 'conflict') throw error; const current = error.body.record; return patchRecord(collection, current, merge(current, change), merge); } } ``` ## Abmelden ```js async function signOut() { await api('POST', '/logout'); // widerruft die Tokens der Person in allen Werkzeugen sessionStorage.removeItem('tokens'); // Im eigenen Fenster auf Wunsch auch aus Stundentakt abmelden; next muss eine eingetragene Rücksprungadresse sein. if (window.parent === window) { location.href = STUNDENTAKT + '/logout?next=' + encodeURIComponent(REDIRECT_URI); } } ``` Meldet sich die Person in Stundentakt ab (oder eine andere im selben Browser an), erfährt das Werkzeug es beim nächsten Aufruf als `token_revoked`. ## Fehler behandeln Jeder Fehler ist `{message, reason}`; entschieden wird nach `reason`, nie nach `message`. | `reason` | Status | Reaktion des Werkzeugs | |---|---|---| | `token_expired` | 401 | mit dem Erneuerungstoken erneuern, Aufruf wiederholen | | `token_revoked`, `token_invalid` | 401 | still neu anmelden (`prompt=none`); kommt `login_required`, Anmelden anbieten | | `wrong_scope` | 403 | mit `tools:write` anmelden | | `wrong_origin` | 403 | Seite läuft nicht auf der Origin der Startadresse: Eintrag prüfen | | `tool_unavailable` | 403 | Eintrag gesperrt oder gelöscht: Hinweis zeigen, nichts mehr senden | | `forbidden` | 403 | die Person darf das nicht: Hinweis zeigen | | `guest_not_supported` | 403 | Gast: nur lokal speichern | | `no_storage` | 403 | Schüler:in ohne Klasse: Records lokal halten | | `not_found` | 404 | Adresse oder ULID falsch, oder nicht dieses Werkzeugs | | `withdrawn` | 404 | die Antwort einer Durchsicht gibt es nicht mehr | | `conflict` | 409 | aktuellen Stand aus `block` bzw. `record` übernehmen oder zusammenführen | | `too_large`, `quota_exceeded` | 413 | weniger speichern bzw. Hinweis auf den Speicher | | `invalid` | 422 | Felder in `errors` | | `not_open` | 422 | `detail`: `not_yet`, `closed` oder `wrong_mode`; Eingabe sperren, Hinweis zeigen | | `too_many_requests` | 429 | `Retry-After` Sekunden warten | | `maintenance` | 503 | `Retry-After` Sekunden warten, dann erneut versuchen | ```js function explain(error) { switch (error.reason) { case 'not_open': return { not_yet: 'Die Aufgabe ist noch nicht offen.', closed: 'Die Abgabe ist geschlossen.', wrong_mode: 'Die Aufgabe ist gerade nur zum Ansehen.' }[error.body.detail]; case 'tool_unavailable': return 'Dieses Werkzeug ist in Stundentakt gesperrt.'; case 'forbidden': return 'Das ist hier nicht erlaubt.'; case 'quota_exceeded': return 'Der Speicher ist voll.'; default: return error.message; } } ``` ## Rahmen oder eigenes Fenster | | im Rahmen (`inline`) | im eigenen Fenster (`full`) | |---|---|---| | Start | Stundentakt rahmt die Startadresse ein | Stundentakt öffnet die Startadresse in einem neuen Tab | | still anmelden | der Rahmen navigiert zu `/oauth/authorize?…&prompt=none`; fehlt dem Browser das Cookie, ruft Stundentakt die Adresse einmal selbst erneut auf, das Werkzeug merkt nichts | das Fenster navigiert zu `/oauth/authorize?…&prompt=none` | | niemand angemeldet | `error=login_required`: Anmeldung in einem neuen Fenster öffnen (ohne `prompt`), danach im Rahmen erneut still | dieselbe Adresse ohne `prompt` führt über die Anmeldeseite und zurück | | Höhe | per `postMessage` melden (`type: 'height'`) | entfällt | | Neu laden | Tokens aus `sessionStorage`, sonst still neu | ebenso | Tokens reisen nie per `postMessage` und nie in einer Adresse; jede Seite des Werkzeugs holt sich ihre eigenen. ## Meine Kurse Ohne Start aus Stundentakt (Lesezeichen, eigene Startseite des Werkzeugs) zeigt das Werkzeug, woran die Person mit ihm arbeitet: `GET me/assignments` nennt ihre Zuweisungen mit Bausteinen **dieses** Werkzeugs, nach Frist sortiert (ohne Frist zuletzt, dann die neueste), und Kurse, deren Stunden auf solche Medien verweisen. Die Klasse kommt nur mit ihrem Namen. In die Seite aus `/docs/developers/quickstart.md` gehört dafür eine Liste und ein Formular für den nächsten Abschnitt: ```html ``` Im Ablauf ersetzt das Werkzeug Schritt b) („ohne Start-Parameter“) durch die Liste: ```js // b) ohne Start-Parameter: anmelden und zeigen, was die Person mit diesem Werkzeug zu tun hat if (!launch) { if (!tokens()) return signInSilently(); $('link-form').hidden = false; return showCourses(); } ``` ```js // Alle Seiten holen (je höchstens 100). async function myAssignments() { const items = []; for (let page = 1; ; page++) { const result = await api('GET', '/me/assignments?per_page=100&page=' + page); items.push(...result.items); if (items.length >= result.total || result.items.length === 0) return items; } } async function showCourses() { const list = $('courses'); list.replaceChildren(); for (const entry of await myAssignments()) { // entry = { assignment, role, document: {ulid, name, type}, group: {name} | null, mode, open_from, closes_at, // open, progress: {done, total, blocks} | null, last_activity, blocks: [ulid], lessons? } const item = document.createElement('li'); const due = entry.closes_at ? ' · bis ' + new Date(entry.closes_at).toLocaleDateString(lang) : ''; // Bei einem Kurs ist progress schon über seine Medien summiert. const done = entry.progress ? ` · ${entry.progress.done} von ${entry.progress.total} abgegeben` : ''; const last = entry.last_activity ? ' · zuletzt ' + new Date(entry.last_activity).toLocaleDateString(lang) : ''; item.append(`${entry.document.name} (${entry.group?.name ?? 'Link'})${due}${done}${last} `); // Jeder Baustein startet das Werkzeug wie ein Start aus Stundentakt im Modus learn. for (const block of entry.blocks) item.append(openButton('Öffnen', entry.assignment, block)); // Ein Kurs bringt seine Stunden mit den Medien mit, die dieses Werkzeug enthalten. for (const lesson of entry.lessons ?? []) { for (const medium of lesson.media) { // Ohne Zuweisung an die Klasse (assignment: null) erreicht die Person das Medium nur über seinen Link. if (!medium.assignment) continue; for (const block of medium.blocks) { item.append(openButton(`${lesson.topic ?? 'Stunde'}: ${medium.name}`, medium.assignment, block)); } } } list.append(item); } if (!list.children.length) status('Noch keine Aufgabe mit diesem Werkzeug.'); } // Dieselbe Adresse, die ein Start aus Stundentakt öffnet; danach läuft alles wie im Schnellstart. function openTask(assignment, block) { location.href = REDIRECT_URI + '?' + new URLSearchParams({ mode: 'learn', assignment, block, lang }); } function openButton(text, assignment, block) { const button = document.createElement('button'); button.textContent = text; button.onclick = () => openTask(assignment, block); return button; } ``` - `role: 'teacher'`: die Lehrer:in der Klasse. `progress` und `last_activity` sind dann `null`; die Klasse wertet sie in Stundentakt aus. - `last_activity`: wann die Person hier zuletzt abgegeben, einen Zwischenstand gespeichert oder dieses Werkzeug ein Ereignis gemeldet hat; bei einem Kurs auch in seinen Medien. `null`, solange nichts davon geschah. - Ein Menüpunkt „Profil bei Stundentakt“ öffnet `profile_url` aus `GET me` in einem neuen Tab. - `open: false` heißt: noch nicht offen, Frist vorbei oder „Nur ansehen“. Genaueres nennt `GET assignments/{a}` (`window.phase`), eine Abgabe antwortet dann `422 not_open`. - Links geteilter Medien erscheinen erst, wenn die Person dort abgegeben oder einen Zwischenstand gespeichert hat. ## Kurs per Stundentakt-Link öffnen Eine Schüler:in kopiert die Adresse aus Stundentakt (`https://stundentakt.eu/m/…`, `/d/…`, einen Kurzlink oder nur den Code von der Tafel, `ABC-DEF`) und fügt sie im Werkzeug ein. `GET links/resolve` löst sie auf, wie die App es täte, und antwortet mit derselben Form wie ein Eintrag aus „Meine Kurse“. ```js async function openPasted(text) { try { const entry = await api('GET', '/links/resolve?url=' + encodeURIComponent(text.trim())); // { assignment, role, document, group, mode, open_from, closes_at, open, progress, blocks, lessons? } if (entry.blocks.length === 1 && !entry.lessons) return openTask(entry.assignment, entry.blocks[0]); // Mehrere Aufgaben dieses Werkzeugs im Medium oder ein Kurs: wählen lassen. const list = $('courses'); list.replaceChildren(); for (const block of entry.blocks) list.append(openButton(entry.document.name, entry.assignment, block)); for (const lesson of entry.lessons ?? []) { for (const medium of lesson.media.filter((m) => m.assignment)) { for (const block of medium.blocks) list.append(openButton(medium.name, medium.assignment, block)); } } } catch (error) { // Fremde Adresse, ein Medium ohne dieses Werkzeug, eine Klasse, in der sie nicht ist: alles dieselbe Antwort. if (error.reason === 'not_found') return status('Unter diesem Link gibt es hier nichts zu tun.'); if (error.reason === 'invalid') return status('Bitte einen Link einfügen.'); throw error; } } $('link-form').onsubmit = (event) => { event.preventDefault(); openPasted(new FormData(event.target).get('link')); }; ``` - Ein Medium führt in die Klasse der Person, die es hat; sonst auf den Link eines geteilten Mediums, das Teilnahme annimmt (`role: 'guest'`). Die Zuweisung des Links legt Stundentakt beim ersten Mal an, wie beim Öffnen in der App. - Ein **Klassencode** nennt kein Medium (`404`): dafür ist „Meine Kurse“ da. - Die Antwort verrät nie, ob es ein Medium gibt, das die Person nicht erreicht. Das Werkzeug sagt bei `404` nur „nichts zu tun“. - Gäste haben kein Token; für sie bleibt nur das Gerät. ## Anzeige je Baustein Ob das Werkzeug im Rahmen der Seite (`inline`) oder in einem eigenen Fenster (`full`) startet, stellt der Eintrag ein. Ein Baustein kann es für sich ändern: `payload.display` ist `inline`, `full` oder `null` (wie der Eintrag). Die Lehrer:in wählt es im Baustein unter „Anzeige“; ein Werkzeug im Autorenmodus kann es mit `PUT blocks/{block}` setzen, etwa weil eine Aufgabe einen großen Bildschirm braucht. ```js // Im Autorenmodus: die Aufgabe braucht Platz, also in einem eigenen Fenster. const { block } = await api('PUT', '/blocks/' + launch.block, { display: 'full' }); // block.payload.display === 'full' // Zurück zur Einstellung des Eintrags (was der Körper weglässt, bleibt). await api('PUT', '/blocks/' + launch.block, { display: null }); // Anderes ist 422 invalid mit errors.display. ``` ```js // Beim Start: woran erkennt das Werkzeug, wie es gerade läuft? Am Fenster selbst. const framed = window.parent !== window; if (framed) reportHeight(); // nur im Rahmen: Höhe per postMessage melden (quickstart.md) ``` - Start und Darstellung lesen den Wert des Bausteins: Die Medium-Ansicht zeigt einen Baustein mit `full` als Karte, die das Werkzeug in einem neuen Tab öffnet, die Bühne ebenso; `/tools/launch/{block}?frame=1` rahmt ihn im Modus `learn` nicht ein, sondern öffnet das Werkzeug selbst. - Der Autorenmodus im Editor bleibt immer ein Rahmen, gleich welche Anzeige. - `GET documents/{d}` und `GET assignments/{a}` nennen den Wert in `blocks[].payload.display` (`null`: wie der Eintrag). --- # Werkzeug-API – ein Lernwerkzeug andocken Ein **Lernwerkzeug** ist eine fremde Webseite (Übungen, Simulationen, Aufgabenformate), die Stundentakt als Baustein in ein Medium einbindet. Stundentakt startet sie; sie meldet die Person per OAuth an (Code mit PKCE), holt mit dem Zugriffstoken ihre Aufgabe, speichert Zwischenstände, meldet Ergebnis und Ereignisse zurück. Die Seite des Werkzeugs wird von Stundentakt nie ausgeführt, nur eingerahmt. Die Gegenstelle im Werkzeug ist `tool-link.js` (`stundentakt-subjects/packages/kit`); dieses Dokument ist der Vertrag dazu. Dieses Dokument ist die Referenz. Einstieg: `/developers` (Seite für Menschen), `/docs/developers/overview.md`, `/docs/developers/quickstart.md`, `/docs/developers/recipes.md`. Maschinenlesbar: `/llms.txt` (nach llmstxt.org), `/llms-full.txt` und `/api/v1/tools/openapi.json` (OpenAPI 3.1, ohne Token, darf 5 Minuten zwischengespeichert werden). ## 1 Überblick - Ein Eintrag unter **Werkzeuge** (`/tools`) beschreibt ein Werkzeug: Name, Start-Adresse, Rücksprungadressen, Anzeige. Jeder Eintrag ist ein öffentlicher OAuth-Client (ohne Secret); seine `client_id` (eine UUID) steht am Eintrag. - Ein Baustein `tool` im Medium verweist auf einen Eintrag und trägt Titel, Aufgabe (`task`) und einen versteckten Teil (`hidden`, nur für die Autor:in und das Werkzeug in ihrer Hand). - **Modi** (`mode` in der Start-Adresse): - `learn`: eine Schüler:in oder eine mitmachende Lehrer:in bearbeitet die Aufgabe. - `review`: eine Lehrer:in liest die abgegebene Antwort einer Schüler:in ihrer Klasse (nur lesen). - `author`: die Lehrer:in schreibt die Aufgabe selbst (Titel, Aufgabe, versteckter Teil). - **Anzeige:** `inline` (Rahmen in der Seite) oder `full` (Karte, die ein eigenes Fenster öffnet). Der Eintrag gibt sie vor; ein Baustein kann sie für sich überschreiben (`payload.display`, Abschnitt 5). - **Rollen:** Lehrer:in (`User`) und Schüler:in (`Member`). Das Werkzeug sieht von einer Schüler:in nur das Pseudonym, von einer Lehrer:in ihren Anzeigenamen („J. Muster“; beides `alias`, Abschnitt 5b), nie eine E-Mail. Ein **Gast** (`Member` ohne Klasse) ist für ein Werkzeug nicht angemeldet: Er bekommt kein Token, das Werkzeug speichert für ihn höchstens lokal. ## 2 Eintragen | Feld | Regel | |---|---| | `name` | Pflicht, kurz | | `launch_url` | Pflicht: `https://` (`http://` nur für `localhost`, `127.0.0.1`, `[::1]`), ohne Benutzer:in/Passwort, ohne `#`, nicht auf Stundentakt selbst | | `redirect_uris` | Rücksprungadressen für OAuth, bis zu 10: `https://` (`http://` nur für `localhost`, `127.0.0.1`, `[::1]` in Entwicklung und Test), ohne Benutzer:in/Passwort, ohne `#`, nicht auf Stundentakt selbst | | `display` | `inline` oder `full` | **Im Werkzeug einstellen:** die `client_id` des Eintrags und als `redirect_uri` genau eine der eingetragenen Rücksprungadressen, Zeichen für Zeichen (Schema, Host, Port, Pfad; die Query zählt beim Vergleich von `next` nicht, bei `redirect_uri` schon). Nutzt ein Werkzeug die Seite selbst als Rücksprung (wie `tool-link.js`: Origin und Pfad der Seite), trägt der Eintrag jede solche Seite ein, z. B. `https://werkzeug.example/embed/`. Dieselben Adressen erlaubt Stundentakt als `next` beim An- und Abmelden (Abschnitt 8); eine andere Seite fürs Abmelden kommt ebenso dazu. Die **Origin** der Adresse (Schema, Host, Port) ist die einzige Origin, von der aus die API antwortet. Ein Eintrag gehört einer Schule oder allen (globale Einträge legt der Betreiber an). Ein **gesperrter** Eintrag (Betreiber) startet nicht mehr, `/oauth/authorize` weist ihn ab (`error=access_denied&reason=tool_unavailable` an die Rücksprungadresse), seine Tokens antworten sofort mit `tool_unavailable`, Erneuern scheitert. Ein gelöschter Eintrag nimmt Client und Tokens mit (danach `token_invalid`). ## 3 Start Stundentakt öffnet die Adresse so (Reihenfolge der Parameter nicht verbindlich): ``` https://werkzeug.example/start?mode=learn&assignment=&block=&lang=de ``` | Modus | Parameter | |---|---| | `learn` | `assignment`, `block` | | `review` | `assignment`, `block`, `response` | | `author` | `document`, `block` | Dazu immer `lang` (`de` oder `en`, die Sprache der Seite, die das Werkzeug öffnet). Das Werkzeug zeigt sich in dieser Sprache und schickt sie als `Accept-Language` mit; danach richten sich `message` eines Fehlers und `entitlements.plan_name` (ohne die Kopfzeile: Englisch). Eigene Parameter in `launch_url` bleiben erhalten, gleichnamige überschreibt Stundentakt. Alle Werte außer `mode` und `lang` sind ULIDs. Die Adresse trägt **kein Token**; das Werkzeug meldet die Person selbst an (Abschnitt 4). Im Modus `inline` steht das Werkzeug in einem Rahmen (`iframe`) einer Stundentakt-Seite (`/tools/launch/{block}?frame=1`), sonst öffnet `/tools/launch/{block}` ein eigenes Fenster. Maßgeblich ist die Anzeige des Bausteins (`payload.display`), ohne eigene die des Eintrags; einen Baustein mit `full` rahmt der Start im Modus `learn` nie ein, auch nicht mit `frame=1`. Der Anbieter muss das Einrahmen durch `https://stundentakt.eu` zulassen (kein `X-Frame-Options: DENY`; `frame-ancestors` nennt Stundentakt). ## 4 Anmelden mit OAuth Code-Ablauf nach RFC 6749 mit PKCE (RFC 7636, nur `S256`), öffentlicher Client ohne Secret. Eine Zustimmung fragt Stundentakt bei eingetragenen, nicht gesperrten Werkzeugen nicht ab. **1. Code holen.** Das Werkzeug erzeugt einen `code_verifier` (43–128 Zeichen aus `A-Z a-z 0-9 - . _ ~`) und daraus die `code_challenge`, und navigiert (im Rahmen oder im eigenen Fenster) zu: ```js const verifier = base64url(crypto.getRandomValues(new Uint8Array(32))); const challenge = base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)))); sessionStorage.setItem('pkce', verifier); location.href = 'https://stundentakt.eu/oauth/authorize?' + new URLSearchParams({ client_id: '', redirect_uri: 'https://werkzeug.example/callback', response_type: 'code', scope: 'tools:write', state: '', prompt: 'none', code_challenge: challenge, code_challenge_method: 'S256', }); ``` Zurück kommt `https://werkzeug.example/callback?code=…&state=…`. `redirect_uri` muss genau eine eingetragene Rücksprungadresse sein, sonst geht nichts zurück (`401 invalid_client`, kein Rücksprung). **`prompt=none`** (still, nach OpenID Connect): Ist die Person in Stundentakt angemeldet, kommt sofort ein Code; sonst `error=login_required` statt der Anmeldeseite. Beim Start aus Stundentakt besteht die Sitzung, also holt das Werkzeug den Code still. Ohne `prompt` zeigt Stundentakt die Anmeldeseite (`/login?next=…`, alle Wege) und kehrt danach zum Authorize-Schritt zurück; ein unvollständiges Lehrer:innen-Konto bestätigt erst die E-Mail bzw. die Einwilligung. Im Rahmen navigiert das Werkzeug seinen eigenen Rahmen zu `/oauth/authorize`. Ein Browser schickt bei einer Navigation, die eine fremde Seite in einem Rahmen auslöst, kein `SameSite=Lax`-Cookie mit, obwohl die Seite darum stundentakt.eu ist. Stundentakt antwortet darauf einmal mit einer kleinen eigenen Seite, die dieselbe Adresse erneut aufruft (`meta refresh`); diese Navigation startet stundentakt.eu selbst, das Sitzungs-Cookie kommt mit, und der Rücksprung folgt wie sonst. Für das Werkzeug ändert sich nichts. **Rahmen auf einer fremden Seite** (nicht Stundentakt): Auch dort antwortet Stundentakt einmal mit dieser Seite. Sie darf in jedem Rahmen stehen (`frame-ancestors *`, ohne `X-Frame-Options`), denn sie zeigt nichts zum Anklicken, nur die Weiterleitung. Ihr zweiter Aufruf kommt von stundentakt.eu selbst und zeigt die Seite nie wieder; weil die äußere Seite fremd ist, schickt der Browser trotzdem kein Cookie, und mit `prompt=none` kommt `login_required` an der Rücksprungadresse an, ohne Schleife. Das Werkzeug bietet dann ein eigenes Fenster zum Anmelden an (Abschnitt 8) und fragt danach still erneut. Ohne `prompt=none` führte der zweite Aufruf zur Anmeldeseite, die in keinem fremden Rahmen steht; im Rahmen also immer `prompt=none`. Jede andere Seite unter `/oauth/authorize` bleibt nicht einbettbar. Rücksprünge ohne Code: | `error` | `reason` | Bedeutung | |---|---|---| | `login_required` | – | `prompt=none`, niemand angemeldet | | `interaction_required` | – | `prompt=none`, Lehrer:innen-Konto unvollständig (E-Mail unbestätigt oder Einwilligung fehlt); ohne `prompt` führt Stundentakt erst dorthin | | `access_denied` | `guest_not_supported` | ein Gast ist für Werkzeuge nicht angemeldet | | `access_denied` | `tool_unavailable` | Eintrag gesperrt | | `invalid_request` | – | `code_challenge_method` ist nicht `S256` | **2. Code tauschen** (`POST /oauth/token`, Formular oder JSON, ohne Cookies): ``` grant_type=authorization_code&client_id=&redirect_uri=https://werkzeug.example/callback &code=&code_verifier= ``` ```json {"token_type": "Bearer", "expires_in": 900, "access_token": "eyJ…", "refresh_token": "def5…"} ``` **3. Erneuern** vor Ablauf oder nach `token_expired`: ``` grant_type=refresh_token&client_id=&refresh_token= ``` Die Antwort hat dieselbe Form; das alte Erneuerungstoken und das alte Zugriffstoken sind danach verbraucht (Rotation). Scheitert das Erneuern (`400 invalid_grant`), holt das Werkzeug still einen neuen Code (`prompt=none`); kommt `login_required`, ist die Person abgemeldet. - **Zugriffstoken:** Träger-Token (`Authorization: Bearer …`), **15 Minuten**. - **Erneuerungstoken:** rotierend, verfällt nach **30 Minuten ohne Erneuern** (so lange wie eine Sitzung in Stundentakt ohne Aktivität). Bleibt die Person dort angemeldet („Angemeldet bleiben“), holt das Werkzeug danach still einen neuen Code. - **Subjekt** (`sub`): `user:` oder `member:`, nie eine interne Nummer. - **Scopes:** siehe Tabelle; ohne Scope gilt keiner (`wrong_scope`), andere Scopes erhält ein Werkzeug nie. - Ein Token gilt für **ein** Werkzeug und **eine** Person; es ist nie mehr als die Person selbst und erreicht weder die KI-/MCP-Schnittstelle noch eine andere Stelle von Stundentakt. - Widerrufen werden Zugriffs- **und** Erneuerungstoken: beim Abmelden in Stundentakt (auch wenn sich im selben Browser eine andere Person anmeldet), beim `POST logout` (Abschnitt 8), beim Sperren oder Löschen des Eintrags und beim Löschen der Person. ### Scopes | Scope | wofür | erlaubt | |---|---|---| | `tools:read` | Modus `review` | alle Routen mit Scope `read` in Abschnitt 5 | | `tools:write` | Modi `learn` und `author` | alle Routen (`read` und `write`) | ### Ablauf im Rahmen und im eigenen Fenster Beide Wege sind derselbe OAuth-Ablauf; sie unterscheiden sich nur darin, wo das Werkzeug navigiert. | Schritt | im Rahmen (`inline`) | im eigenen Fenster (`full`, direkter Aufruf, F5) | |---|---|---| | Start | Stundentakt rahmt `launch_url?mode=…&lang=…` ein, die Person ist angemeldet | `/tools/launch/{block}` öffnet dieselbe Adresse; ein Lesezeichen oder F5 öffnet sie direkt | | Code | der Rahmen navigiert zu `/oauth/authorize?…&prompt=none` | das Fenster navigiert zu `/oauth/authorize?…&prompt=none` | | ohne Cookie | Stundentakt antwortet einmal mit der Nachfrage-Seite, die dieselbe Adresse selbst erneut aufruft; danach kommt der Code | – | | niemand angemeldet | `error=login_required`: das Werkzeug bietet „In Stundentakt anmelden“ an, öffnet den Authorize-Schritt **ohne** `prompt` in einem neuen Fenster und fragt danach im Rahmen erneut still | `error=login_required`: dieselbe Adresse ohne `prompt` führt über `/login?next=…` und zurück | | Konto unvollständig | `error=interaction_required`: wie oben ohne `prompt` | ohne `prompt` erst E-Mail-Bestätigung bzw. Einwilligung, dann zurück | | Token | `POST /oauth/token` mit `code_verifier` | ebenso | | F5 / neuer Tab | Tokens am besten im `sessionStorage` des Werkzeugs; fehlen sie, still neu mit `prompt=none` | ebenso | | Abmelden | `POST logout` (Abschnitt 8) | `POST logout`, dann auf Wunsch `/logout?next=` | Tokens reisen nie über `postMessage`, nie in einer Adresse und nie zwischen Rahmen und Seite: jede Seite des Werkzeugs holt sich ihre eigenen. ## 5 Routen Basis: `https://stundentakt.eu/api/v1/tools`. Alle Antworten sind JSON. Fehler siehe Abschnitt 6. | Methode | Pfad | Scope | Zweck | |---|---|---|---| | GET | `documents/{document}` | read | Modus `author`: Name des Mediums, Bausteine dieses Werkzeugs samt `hidden`, soweit die Person sie ändern darf, und das ganze Medium (`content`) | | GET | `assignments/{assignment}` | read | Modi `learn`, `review`: Zuweisung, Fenster, `me`, Bausteine dieses Werkzeugs, das ganze Medium (`content`), eigener Fortschritt (`progress`) | | PUT | `blocks/{block}` | write | `author`: `title`, `task`, `hidden`, `display`, `complete` (`false` speichert einen Entwurf, den keine Klasse sieht), `updated_at` als Vorbedingung; alles optional | | GET | `assignments/{assignment}/blocks/{block}/draft` | read | eigener Zwischenstand (`draft.state`) und eigene Abgabe (`response`) | | PUT | `assignments/{assignment}/blocks/{block}/draft` | write | `{state}` speichern | | POST | `assignments/{assignment}/blocks/{block}/response` | write | Ergebnis abgeben: `done`, `score`, `max_score`, `state`, `attachments` | | GET | `assignments/{assignment}/blocks/{block}/response/{response}` | read | `review`: eine Antwort der Klasse lesen | | POST | `assignments/{assignment}/blocks/{block}/attachments` | write | Datei hochladen (`multipart`, Felder `type`=`file` und `attachment`; dieselbe Route-Logik wie das Antwortformular der App); die ULID kommt in `attachments` des Ergebnisses | | POST | `assignments/{assignment}/events` | write | Lernereignisse im Unterricht melden | | POST | `events` | write | Lernereignisse ohne Unterricht melden (Person + Werkzeug) | | GET | `blocks/{block}/note` | read | eigene Notiz zum Baustein | | PUT | `blocks/{block}/note` | write | `{note}` speichern (leer löscht) | | GET | `me` | read | wer angemeldet ist und was ihr Abo freischaltet (Abschnitt 5b) | | GET | `me/assignments` | read | „Meine Kurse“: Zuweisungen der Person mit Bausteinen dieses Werkzeugs (Abschnitt 5c) | | GET | `links/resolve` | read | eine Stundentakt-Adresse oder einen Code als Zuweisung der Person öffnen (`?url=`, Abschnitt 5c) | | POST | `logout` | read | Tokens der Person in allen Werkzeugen widerrufen | | GET | `collections/{collection}/records` | read | eigene Records einer Datenart, mit `?scope=shared` die für die Person freigegebenen anderer (Abschnitt 5a) | | GET | `collections/{collection}/records/{record}` | read | einen Record lesen: eigener oder freigegebener | | POST | `collections/{collection}/records` | write | Record anlegen: `data`, `schema`, `visibility` | | PATCH | `collections/{collection}/records/{record}` | write | eigenen Record ändern: `data`, `schema`, `visibility`, Pflicht `updated_at` | | DELETE | `collections/{collection}/records/{record}` | write | eigenen Record löschen | | GET | `records/{record}` | – | öffentlichen Record lesen, **ohne Token** | Antworten im Einzelnen: - `GET documents/{d}`: `document` (`ulid`, `name`, `type`), `blocks` (die Bausteine dieses Werkzeugs: `ulid`, `type`, `payload` mit `tool`, `title`, `task`, `display`, dazu `updated_at` und `hidden`, wenn die Person den Baustein ändern darf), `content` (siehe unten). - `payload.display`: `inline`, `full` oder `null`. `null` heißt: wie am Eintrag eingestellt. Die Lehrer:in wählt es im Baustein („Anzeige“), das Werkzeug setzt es mit `PUT blocks/{b}`; jeder andere Wert ist `422 invalid`. - `GET assignments/{a}`: `assignment` (`ulid`, `mode`, `visible_from/until`, `open_from`, `closes_at`; `open_from` ist der Beginn, `closes_at` die Frist), `document`, `window` (`phase`, `takes_answers`), `me` (`role`: `teacher|student|guest`, `alias`: derselbe Name wie in `GET me`, bei einer Schüler:in ihr Pseudonym, bei einer Lehrer:in ihr Anzeigename), `blocks` (wie oben, dazu die Bausteine dieses Werkzeugs, die die Klasse ergänzt hat), `content` und `progress`. - `content`: das ganze Medium in der Reihenfolge der Seite, ein Kind direkt hinter seinem Eltern-Baustein. Jeder Eintrag hat `ulid`, `type`, `position`, `parent` (ULID oder `null`) und `own`: - `own: true`: ein Baustein dieses Werkzeugs, in derselben Form wie in `blocks`. - `own: false`: jeder andere Baustein (Text, Bild, Aufgabe, ein anderes Werkzeug …) mit `text`, der lesbaren Fassung des Bausteins (Markdown, dieselbe wie für die KI-Schnittstelle). `payload` (öffentlicher Teil) nur für die Person, die den Baustein ändern darf. `solution` nur, wo die App die Lösung zeigt: nach der Frist der Klasse, der Lehrer:in der Klasse immer, nie über `documents/{d}`. - Bild und Galerie tragen `images: [{url, alt}]`. `url` ist eine signierte Adresse, die 5 Minuten gilt und ohne Cookie von der Seite des Werkzeugs lädt (``); danach holt das Werkzeug den Eintrag neu. Sie geht nur an eine Person, die den Baustein sehen darf. - Ein Verweis auf ein Medium (Kurs: die Stunde `lesson` mit ihren Verweisen als Kindern) trägt `medium`: `{ulid, name, type, assignment}` mit der Zuweisung dieses Mediums an die Klasse (oder `null`); nimmt die Person dort teil, dazu ihr `progress` (Form wie unten). `medium` ist `null`, solange die Klasse das Medium nicht öffnen kann. Eine Stunde, die noch bevorsteht, zeigt der Klasse nur sich selbst, ohne ihre Kinder. - Wer das Medium baut (`documents`) oder die Klasse leitet (`assignments`), sieht alle Bausteine. Alle anderen sehen, was die Klasse sieht: Bausteine nur für Lehrer:innen und unfertige Bausteine fehlen samt ihren Kindern. Beiträge einer Klasse (Karten, Feed) gehören nicht zum Medium und fehlen. - `progress`: `{done, total, blocks: [{ulid, done}]}`, die eigenen Antworten der Person auf die Aufgaben, die die Klasse sieht; dieselbe Zählung wie der Fortschritt in der App, Antworten einer Live-Runde zählen nicht. - `GET …/draft`: `{draft: {state, updated_at} | null, response: {payload: {done, score, max_score, state}, submitted_at, returned} | null}`. Eine Abgabe löscht den Entwurf: Steht ein Entwurf neben einer Abgabe, ist er neuer als sie. - `GET …/response/{r}`: `{ulid, alias, payload, submitted_at, returned}`; `alias` ist der Name wie in `GET me`, bei einer Schüler:in ihr Pseudonym. Gibt es die Antwort nicht mehr (zurückgezogen oder entfernt), `404 withdrawn`. - `PUT blocks/{b}`: Antwort `{complete, incomplete, block}`. Was der Körper weglässt, bleibt (auch `hidden` und `display`; `display: null` gibt die Anzeige an den Eintrag zurück). Mit `updated_at` (so, wie das Werkzeug es zuletzt gelesen hat) speichert die Route nur, wenn sich die Aufgabe seitdem nicht geändert hat, sonst `409 conflict` mit dem aktuellen Stand in `block`; ohne `updated_at` gewinnt der letzte Aufruf. Verglichen wird auf die Sekunde. - `POST …/response`: `{ok: true}`. Eine neue Abgabe ersetzt die frühere. Abgabe und Datei sind dieselben Wege wie das Antwortformular der App (gleiche Action, gleiche Regeln), nur mit dem Token statt der Sitzung. `score` ist das Wort des Werkzeugs; niemand prüft es nach. - `POST …/events` und `POST events`: Körper `{events: [{block?, verb, code?, object?, result?, timestamp?}]}`, Antwort `201 {recorded: n}`. Die Form folgt einer xAPI-Aussage (Person, Verb, Objekt, Ergebnis, Zeit), ohne Lernspeicher und ohne JSON-LD. Person und Werkzeug sind immer die des Tokens, nie aus dem Körper; ein Werkzeug schreibt also nie ein Ereignis für ein anderes. Ein Aufruf wird ganz oder gar nicht gespeichert. - **Im Unterricht** (`assignments/{a}/events`): die Person nimmt an der Zuweisung teil (wie bei der Abgabe); das Ereignis gehört zur Zuweisung, mit `block` auch zum Baustein. Nur Ereignisse mit `block` zählen in der Auswertung der Klasse. - **Ohne Unterricht** (`events`): z. B. eine gelernte Vokabel im freien Gebrauch. Das Ereignis gilt nur Person und Werkzeug: kein `block` (sonst `422 invalid`), als `object` nur ein eigener `record`. - `block`: ULID eines Bausteins dieses Werkzeugs in der Zuweisung; ohne `block` gilt das Ereignis der Zuweisung. - `verb`: freies Wort des Werkzeugs (≤ 40 Zeichen). Empfohlen, weil Stundentakt sie auswertet: `run` (ausgeführt), `error` (Fehler, mit `code`), `step` (Schritt geschafft), `submit` (abgegeben), `reset` (neu begonnen). - `code`: freier Fehlercode des Werkzeugs (≤ 80 Zeichen), z. B. `err.script.indent`. - `object`: `{type, id}` mit `type` = `block` (ULID eines Bausteins dieses Werkzeugs in der Zuweisung) oder `record` (ULID eines eigenen Records der Person in diesem Werkzeug; ein freigegebener fremder Record zählt nicht). Passt das Objekt nicht, `422 invalid` mit dem Feld in `errors`. Wird der Record gelöscht, bleibt das Ereignis ohne Objekt stehen. - `result`: nur `success` (`true`/`false`), `score` und `duration`, höchstens 2 KB. `score` ist eine Zahl von 0 bis 1 oder `{raw?, min?, max?, scaled?}` (Zahlen, `min` ≤ `raw` ≤ `max`, `scaled` von 0 bis 1); eine Zahl wird als `{scaled}` gespeichert. `duration` ist eine Dauer nach ISO 8601 (`PT1M30.5S`, bis `P30D`, Tage, Stunden, Minuten, Sekunden mit bis zu drei Nachkommastellen) oder eine ganze Zahl Millisekunden; gespeichert wird sie in Millisekunden. - `timestamp`: Zeit des Werkzeugs nach ISO 8601 mit Zone (`2026-10-28T09:15:00.250Z`, `…+02:00`). Sie wird auf das Fenster der letzten 24 Stunden **geklemmt**: eine Zeit in der Zukunft gilt als jetzt, eine ältere als vor 24 Stunden; ohne `timestamp` gilt jetzt. Daneben speichert Stundentakt die eigene Eingangszeit. Ein Werkzeug, das Ereignisse offline sammelt, meldet sie also binnen eines Tages. - Andere Felder werden nicht gelesen. Es gibt keinen Verweis auf eine Antwort: die meisten Ereignisse entstehen vor der Abgabe, und eine Abgabe wird ersetzt. - `GET/PUT blocks/{block}/note`: `{note: string|null}`. Es ist die Notiz, die jede Person unter jedem Baustein führt; sie gehört ihr allein und ist nie eine Antwort. - Ein Baustein eines **anderen** Werkzeugs ist `404 not_found`. - **Link und öffentlich:** Ein per Link geteiltes oder öffentliches Medium, das Teilnahme annimmt, hat eine Zuweisung ohne Klasse; der Start nennt sie wie jede andere. Eine angemeldete Schüler:in (aus jeder Klasse) und eine Lehrer:in nehmen dort teil wie ein Gast, unter sich selbst (`me.role` ist `guest`). Die Lehrer:in der Schule des Mediums leitet sie (`teacher`). - **Gäste** sind für ein Werkzeug nicht angemeldet: Sie bekommen kein Token (`/oauth/authorize` antwortet `error=access_denied&reason=guest_not_supported`), jede Route antwortet ohne Token `401 token_invalid`; ein Werkzeug speichert für sie nur auf dem Gerät. ## 5a Freie Daten (Records) Was ein Werkzeug außerhalb einer Aufgabe für eine Person aufbewahrt (eigene Programme, Vokabeln, Einstellungen), legt es als **Record** in einer **Datenart** (`collection`) ab. Kein Werkzeug legt Tabellen an; jede Datenart ist ein Name, den das Werkzeug frei wählt: `[a-z0-9_-]`, 1 bis 64 Zeichen (ein anderer Name: `404 not_found`, beim Anlegen `invalid`). Das Werkzeug ist immer das des Tokens, nie eines aus der Adresse: Werkzeug A erreicht keinen Record von Werkzeug B, auch nicht mit dem Token derselben Person. - **Record:** `{id, collection, data, schema, visibility, created_at, updated_at, owner}`. `id` ist die ULID. `data` ist ein JSON-Objekt oder eine Liste, höchstens 64 KB (Bytes des UTF-8-JSON). `schema` ist die Formatnummer des Werkzeugs (ganze Zahl ≥ 1, Standard 1): Stundentakt liest `data` nie und hebt keine alten Records an; das macht das Werkzeug beim Lesen. Zeiten sind ISO 8601 in UTC mit Mikrosekunden. - **`owner`:** `{kind, alias, self}`; `kind` ist `student` oder `teacher`, `alias` bei einer Schüler:in ihr Pseudonym, bei einer Lehrer:in ihr Anzeigename („J. Muster“), nie eine E-Mail; `self` ist `true` für die eigene. - **`GET …/records`:** `sort` = `-updated` (Standard), `updated`, `-created`, `created`; `page` (ab 1), `per_page` (Standard 50, höchstens 100). Antwort `{items, page, per_page, total}`. Ohne `scope` nur eigene Records; `scope=shared` nur Records anderer Personen dieses Werkzeugs, die die Person lesen darf. - **`POST …/records`:** `{data, schema?, visibility?}` → `201` mit dem Record. - **`PATCH …/records/{id}`:** `{data?, schema?, visibility?, updated_at}`. `updated_at` ist Pflicht und so zu senden, wie das Werkzeug es zuletzt gelesen hat; hat sich der Record seitdem geändert, `409 conflict` mit dem aktuellen Stand in `record`. Verglichen wird auf die Mikrosekunde, zwei Speicherungen in derselben Sekunde sind also verschieden. Was der Körper weglässt, bleibt. - **`DELETE …/records/{id}`:** `204`. - **Freigabe** (`visibility`, nur die Eigentümer:in setzt sie; jede Stufe schließt die vorige ein): - `private` (Standard): nur sie selbst. - `group`: wer mit ihr eine aktive Klasse teilt – die Schüler:innen und die Lehrer:innen der Klasse, auch das Elternteil in der Klasse seines Kindes („Meine Kinder“). - `team`: dazu, wer zu einem ihrer Teams gehört – die Lehrer:innen der Schule (bzw. des eigenen Bereichs) und die Schüler:innen der aktiven Klassen darin. Die Teams einer Schüler:in sind die ihrer aktiven Klassen. - `public`: jede:r mit der ULID, auch ohne Token über `GET records/{id}`. In `scope=shared` erscheint er nur für Personen, die über `group` oder `team` verbunden sind; die Liste ist kein öffentliches Verzeichnis. - Klassen im Papierkorb verbinden niemanden. Andere lesen nur; ändern oder löschen sie, `403 forbidden`. Ein Record, den die Person nicht lesen darf, ist `404 not_found` (nie `403`), damit sein Dasein nicht verraten wird. - **Speicher:** Die Größe von `data` zählt gegen das Team, dessen Abo die Person trägt (Abschnitt 5b); Grenze und Verbrauch nennt `GET me` unter `entitlements.records`. Eine Schüler:in ohne aktive Klasse hat keinen Speicher: `403 no_storage`. Ist das Team voll, `413 quota_exceeded`. - **Öffentlich ohne Token:** `GET /api/v1/tools/records/{id}` antwortet nur für `public`, sonst `404`; dieselbe Form, `owner.self` ist `false`. Gedrosselt je Adresse (120 je Minute). - **Gäste** haben kein Token und damit keine Records. ## 5b Abo: `GET me` ```json { "kind": "member", "alias": "Dachs Emil", "profile_url": "https://stundentakt.eu/me", "entitlements": { "plan": "pro", "plan_name": "Pro", "features": {"ai_pro_model": false}, "ai": null, "records": {"limit_bytes": 50000000, "own_bytes": 1234, "record_max_bytes": 65536} } } ``` - `kind`: `user` (Lehrer:in, Elternteil) oder `member` (Schüler:in, Kind). - `alias`: der Name, den die Person außerhalb einer Klasse trägt: bei einer Schüler:in ihr Pseudonym, bei einer Lehrer:in ihr Anzeigename („J. Muster“). Nie ein echter Name einer Schüler:in, nie eine E-Mail, nie eine ID. - `profile_url`: wo die Person sich in Stundentakt selbst verwaltet, je nach Art: Lehrer:in `/settings`, Schüler:in `/me`. Ein Werkzeug öffnet sie in einem neuen Tab (etwa „Profil bei Stundentakt ↗“), nie im eigenen Rahmen. - `entitlements`: was das Abo freischaltet, ohne Preis, Team oder Abrechnung. - `plan`: `free`, `pro` oder `premium`; `plan_name` dessen Name in der Sprache der Anfrage. - `features`: Schalter des Plans als Map (`true` = freigeschaltet). `ai_pro_model`: das bessere KI-Modell. Ein Schalter, den ein Plan sperrt, steht mit `false` darin; fehlt ein Schalter, ist er offen. - `ai`: das KI-Kontingent der Lehrer:in im laufenden Monat, `{monthly_tokens, remaining_tokens}` (Anzahl Tokens). Eine Schüler:in hat keines (`null`). Ein Werkzeug ruft selbst keine KI auf; es liest hier nur, was übrig ist. - `records`: Speicher der freien Daten (Abschnitt 5a) in Bytes: `limit_bytes` des Teams, das sich alle seine Mitglieder teilen (`0`: kein Speicher), `own_bytes` der eigenen Records über alle Werkzeuge, `record_max_bytes` je Record. Den Verbrauch der anderen nennt Stundentakt nie; ist das Team voll, antwortet das Schreiben mit `413 quota_exceeded`. **Wessen Abo?** Ein Abo gehört immer einem Team (eigener Bereich einer Lehrer:in oder Schule). | Person | trägt das Abo von | |---|---| | Lehrer:in | dem besten ihrer Teams: eigener Bereich und ihre Schulen | | Schüler:in | dem besten der Teams ihrer aktiven Klassen (Klassen im Papierkorb zählen nicht) | | Kind eines Elternteils („Meine Kinder“) | dem eigenen Bereich des Elternteils, denn dort liegt die Klasse des Kindes | | Gast | niemandem: nur das kostenlose Angebot, und ohne Token ohnehin kein `me` | „Das beste“ ist der Plan mit dem höchsten Rang in der Reihenfolge der Konfiguration (`free` < `pro` < `premium`). Bei gleichem Plan gewinnt ein eigener Bereich vor einer Schule, danach das älteste Team. Dasselbe Team zählt den Speicher der Records. ## 5c Meine Kurse und Links: `GET me/assignments`, `GET links/resolve` Beide antworten mit derselben Form je Zuweisung (`ToolAssignment` in der OpenAPI-Beschreibung): ```json { "assignment": "01k…", "role": "student", "document": {"ulid": "01k…", "name": "Brüche üben", "type": "page"}, "group": {"name": "8b"}, "mode": "interact", "open_from": null, "closes_at": "2026-11-04T23:59:00+01:00", "open": true, "progress": {"done": 1, "total": 3, "blocks": [{"ulid": "01k…", "done": true}]}, "last_activity": "2026-10-28T14:05:12+01:00", "blocks": ["01k…"] } ``` - `role`: `teacher` (leitet die Klasse), `student` oder `guest` (auf dem Link), wie `me.role` in `GET assignments/{a}`. - `group`: nur der Name der Klasse, nie ihre Mitglieder, ihr Code oder eine Zahl; `null` auf dem Link. - `open`: ob die Klasse jetzt Antworten annimmt (Fenster und Modus). Die Lehrer:in der Klasse darf auch außerhalb. - `progress`: der eigene Fortschritt wie in `GET assignments/{a}`; für die Lehrer:in der Klasse `null` (sie zählt nie als Klasse und liest die Auswertung in Stundentakt). Bei einem Kurs die Summe: die Aufgaben des Kurses selbst und jedes Medium aus `lessons` (mit `progress`) einmal, auch wenn es in mehreren Stunden steht; `blocks` nennt alle. „3 von 7 abgegeben“ ist also `progress.done` von `progress.total`. - `last_activity`: wann die Person hier zuletzt abgegeben, einen Zwischenstand gespeichert oder **dieses** Werkzeug ein Ereignis gemeldet hat (ISO 8601); bei einem Kurs auch in den Medien aus `lessons`. `null`, solange nichts davon geschah, und für die Lehrer:in der Klasse. - `blocks`: die ULIDs der Bausteine dieses Werkzeugs im Medium, die die Person sieht (mit ihnen startet das Werkzeug wie mit `launch.block`). - `lessons` (nur bei einem Kurs): die Stunden, die auf ein Medium mit einem Baustein dieses Werkzeugs verweisen, `[{ulid, topic, media: [{ulid, name, type, assignment, progress?, blocks}]}]`. `medium` wie in `content`, dazu `blocks` dieses Mediums. Eine Stunde, die noch bevorsteht, zeigt der Klasse keine Medien und fehlt dann. **`GET me/assignments`** (`?page=1&per_page=50`, höchstens 100): `{items, page, per_page, total}`. - Enthält nur Zuweisungen, deren Medium einen Baustein **dieses** Werkzeugs trägt (auch einen, den die Klasse ergänzt hat), und Kurse, deren Stunden auf solche Medien verweisen. Ein Werkzeug erfährt nichts von den Aufgaben anderer Werkzeuge. - Schüler:in: ihre aktiven Klassen, solange die Klasse die Zuweisung sieht (Sichtbarkeitsfenster), und Links geteilter Medien, auf denen sie schon abgegeben oder einen Zwischenstand gespeichert hat. - Lehrer:in: die Klassen, die sie unterrichtet (`role: teacher`, auch außerhalb des Fensters), und Links, auf denen sie mitgemacht hat. Klassen im Papierkorb fehlen. - Reihenfolge: nach Frist (`closes_at`, früheste zuerst, ohne Frist zuletzt), dann die neueste Zuweisung zuerst. **`GET links/resolve?url=…`**: die Zuweisung, die die Person über diese Adresse erreicht. - `url`: eine Adresse dieser Instanz, absolut (nur die eigene Origin oder die Kurzlink-Domain) oder relativ (`/m/…`), oder ein Code allein (`ABC-DEF`, Groß- und Kleinschreibung und Bindestrich egal). Erkannt werden `/d/{medium}`, `/m/{medium}`, `/m/{medium}/class/{klasse}`, `/a/{zuweisung}`, `/stage/medium/{medium}`, `/stage/block/{baustein}`, `/stage/slides/{baustein}`, `/live/{runde}` und `/live/{runde}/play` sowie Kurzlinks (`/{code}`) eines Mediums, einer Zuweisung oder einer Live-Runde. - Aufgelöst wird wie in der App: ein Medium führt in die Klasse der Person, die es hat (eine in der Adresse genannte Klasse zuerst, sonst eine, die es jetzt sieht, die neueste zuerst); hat keine ihrer Klassen es, auf den Link eines per Link geteilten oder öffentlichen Mediums, das Teilnahme annimmt (`role: guest`). Eine Zuweisung oder Runde, an der die Person nicht teilnimmt, führt wie in der App auf ihr Medium. - Ein Klassencode nennt eine Klasse, kein Medium: `404`. Ein Werkzeug listet ihre Aufgaben mit `GET me/assignments`. - `404 not_found` für alles, was die Person nicht erreicht, was keinen Baustein dieses Werkzeugs (und als Kurs keine Stunde mit einem solchen Medium) hat, für eine fremde Adresse und für Unsinn. Ob es das Medium gibt, verrät die Antwort nie. Ohne `url`: `422 invalid`. ## 6 Fehler Jeder Fehler ist `{message, reason}` (bei `invalid` zusätzlich `errors` je Feld, bei `not_open` `detail` und `errors`, bei `conflict` `block` bzw. `record`). Maßgeblich ist `reason`. | `reason` | Status | Ursache | wer behebt es | |---|---|---|---| | `token_expired` | 401 | Zugriffstoken abgelaufen | Werkzeug: erneuern (`refresh_token`) | | `token_revoked` | 401 | widerrufen: abgemeldet, durch Erneuern ersetzt, jemand anderes hat sich im Browser angemeldet | Werkzeug: still neu anmelden (`prompt=none`), sonst die Person | | `token_invalid` | 401 | kein Token, fremdes oder kaputtes Token, Token eines gelöschten Eintrags oder einer gelöschten Person | Werkzeug: neu anmelden | | `wrong_scope` | 403 | Lese-Token auf einer schreibenden Route | Werkzeug: mit `tools:write` anmelden | | `wrong_origin` | 403 | Anfrage kommt nicht von der Origin der `launch_url` | Anbieter: Adresse am Eintrag prüfen | | `tool_unavailable` | 403 | Eintrag gesperrt oder gelöscht | Betreiber bzw. Schule, die ihn eingetragen hat | | `forbidden` | 403 | die Person darf das hier nicht (keine Teilnahme, fremde Klasse, fremder Record) | niemand; das Werkzeug zeigt es | | `guest_not_supported` | 403 | ein Gast ist für Werkzeuge nicht angemeldet (Rücksprung von `/oauth/authorize`; zweite Linie der API) | niemand; das Werkzeug speichert lokal | | `no_storage` | 403 | eine Schüler:in ohne aktive Klasse hat keinen Speicher für Records | Lehrer:in: Schüler:in in eine Klasse aufnehmen | | `not_found` | 404 | nichts dieses Namens oder nichts, was dieses Werkzeug besitzt | Werkzeug: Adresse prüfen | | `withdrawn` | 404 | die Antwort einer Durchsicht gibt es nicht mehr (zurückgezogen oder entfernt) | niemand; das Werkzeug zeigt es | | `conflict` | 409 | Aufgabe oder Record wurde seit `updated_at` geändert; `block` bzw. `record` ist der aktuelle Stand | Werkzeug: aktuellen Stand übernehmen oder zusammenführen | | `too_large` | 413 | `state`, `task`, `hidden` oder `data` eines Records über 64 KB | Werkzeug: weniger speichern | | `quota_exceeded` | 413 | der Speicher für Records des Teams ist voll | Person: Records löschen; Team: größeres Abo | | `invalid` | 422 | Körper passt nicht; `errors` nennt die Felder | Werkzeug | | `not_open` | 422 | die Klasse nimmt jetzt keine Antwort an; `detail`: `not_yet` (noch nicht offen), `closed` (Frist vorbei oder nicht mehr sichtbar), `wrong_mode` („Nur ansehen“ oder eine Live-Runde hält den Baustein zurück) | Lehrer:in der Klasse: Fenster oder Modus | | `too_many_requests` | 429 | zu viele Aufrufe (600 je Person und Minute; öffentlicher Record 120 je Adresse und Minute) | Werkzeug: `Retry-After` Sekunden warten | | `maintenance` | 503 | Stundentakt wird gewartet | niemand; das Werkzeug wartet `Retry-After` Sekunden und versucht es erneut | `/oauth/token` antwortet mit den Fehlern nach RFC 6749 (`{error, error_description}`, z. B. `invalid_grant`), nur in der Wartung mit `maintenance` wie oben. ## 7 Browser-Regeln - **CORS:** Antwort nur für die Origin der `launch_url` (`Access-Control-Allow-Origin` genau diese, nie `*`), **ohne** Cookies (`credentials: 'omit'`). Der Vorab-Aufruf (`OPTIONS`) braucht kein Token. Jede Antwort, auch ein 401, ein 429 und die Wartung, trägt die CORS-Kopfzeilen und `Access-Control-Expose-Headers: Retry-After`, damit das Werkzeug die Wartezeit lesen kann. Eine andere Origin erhält `wrong_origin`. `/oauth/token` antwortet zusätzlich den Origins der Rücksprungadressen. - **Cache:** Jede Antwort der Werkzeug-API trägt `Cache-Control: no-store`, Fehler eingeschlossen; Antworten sind immer die einer Person. - **Wartung:** Während Stundentakt gewartet wird (`php artisan down`), antworten `/api/v1/tools/*` und `/oauth/token` mit `503 {message, reason: "maintenance"}`, `Retry-After` in Sekunden (`--retry` der Wartung, sonst 300) und den CORS-Kopfzeilen; der Vorab-Aufruf antwortet weiter. Die Seiten der App zeigen ihre Wartungsseite wie immer. - **Rahmen:** Stundentakt erlaubt die Origin des Werkzeugs in `frame-src`, nur auf Seiten, die den Baustein zeigen. - **Sandbox:** Der Rahmen trägt `allow-scripts allow-same-origin allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-downloads`, keinen Zugriff auf Stundentakt selbst. ## 8 Nachricht `height` und Abmelden Das Werkzeug meldet seine Höhe an `window.parent`: ```js parent.postMessage({ source: 'stundentakt-lernobjekt', v: 1, type: 'height', height: 640 }, '*'); ``` Nur `height` (px, > 0, höchstens 20000) wird beachtet, jede andere Nachricht verworfen. Stundentakt glaubt sie nur aus dem eigenen Rahmen und von der Origin des Werkzeugs. Tokens reisen nie per Nachricht. Hat das Werkzeug eine Abmelden-Funktion, ruft es `POST logout` auf: das widerruft Zugriffs- und Erneuerungstoken der Person in allen Werkzeugen. Danach vergisst es seine Tokens. Das Abmelden in Stundentakt widerruft sie ebenso; das Werkzeug erfährt es beim nächsten Aufruf als `token_revoked`. ### Anmelden und Abmelden im eigenen Fenster Anmelden geht immer über `/oauth/authorize` (Abschnitt 4); ist niemand angemeldet, führt Stundentakt über `/login?next=` und zurück. `next` übersteht jeden Zwischenschritt (E-Mail-Bestätigung, Einwilligung, Klassencode → PIN, Anmeldekarte → PIN, beste.schule). Erlaubt sind Pfade von Stundentakt und **eingetragene Rücksprungadressen** eines nicht gesperrten Werkzeugs (gleiche Origin und gleicher Pfad, die Query ist frei); alles andere wird verworfen. Wer nach dem Abmelden auf eine andere Seite will, trägt sie als Rücksprungadresse ein. **Übergabeseite `GET /continue?next=…`:** Die Seiten von Stundentakt tragen `form-action 'self'`, und das gilt für jede Weiterleitung, der ein abgeschicktes Formular folgt. Endet ein Formular (Abmelden, PIN, Einwilligung, E-Mail-Bestätigung erneut senden, Klasse hinzufügen) oder die Rückkehr von beste.schule bei einer Werkzeug-Adresse oder bei `/oauth/authorize`, leitet Stundentakt darum erst auf diese eigene Seite. Sie prüft `next` erneut wie oben (fremde Adresse oder inzwischen gesperrtes Werkzeug: Startseite) und navigiert per `meta refresh` dorthin, mit Link als Rückfall; das ist eine neue Navigation, kein Formular. Für das Werkzeug ändert sich nichts: am Ende steht dieselbe Adresse mit Code bzw. `error`. Ein `GET` (z. B. `/logout?next=…` ohne Anmeldung) leitet direkt weiter. | Adresse | Wirkung | |---|---| | `GET /login?next=…` | Anmeldeseite mit allen Wegen (Konto, beste.schule, Klassencode, Anmeldekarte) | | `GET /login/beste-schule?next=…` | geht sofort zu beste.schule; Lehrer:in und Schüler:in, das Konto entscheidet | | `GET /logout?next=…` | fragt nach und meldet erst mit dem Knopf ab (`POST /logout`), danach `next` | Lehnt beste.schule ab oder bricht die Person ab, kommt sie mit `error=access_denied&reason=…` auf `next` zurück: `cancelled` (abgebrochen), `failed` (technischer Fehler), `function_account` (Funktionskonto), `unknown_account` (weder Lehrer:in noch Schüler:in), `email_missing`, `email_unconfirmed` (Adresse ohne Bestätigung, Konto nicht verknüpft), `no_class` (Schüler:in ohne gekoppelte Klasse). ## 9 Grenzen | Grenze | Wert | |---|---| | `state`, `task`, `hidden` | je 64 KB (65 536 Bytes des JSON) | | Record (`data`) | 64 KB (65 536 Bytes des UTF-8-JSON) | | Records je Team | 50 MB (50 000 000 Bytes, Summe aller `data`; je Abo einstellbar, siehe `entitlements.records`) | | Datenart (`collection`) | 1–64 Zeichen `[a-z0-9_-]` | | Records je Seite | 50 Stück, höchstens 100 | | Zuweisungen je Seite (`me/assignments`) | 50 Stück, höchstens 100 | | `url` in `links/resolve` | 2 048 Zeichen | | Ereignisse je Aufruf | 100 Stück; `verb` ≤ 40 Zeichen, `code` ≤ 80 Zeichen, `result` ≤ 2 KB (Bytes des JSON) | | `timestamp` eines Ereignisses | geklemmt auf die letzten 24 Stunden | | Notiz | 10 000 Zeichen | | Aufrufe | 600 je Person und Minute | | öffentlicher Record ohne Token | 120 Aufrufe je Adresse und Minute | | Dateien | zählen gegen den Speicher der Schule der Klasse | | Zugriffstoken | 15 Minuten (`TOOL_ACCESS_TOKEN_MINUTES`) | | Erneuerungstoken | 30 Minuten ohne Erneuern (`TOOL_REFRESH_TOKEN_MINUTES`, Standard `SESSION_LIFETIME`) | | Bildadresse in `images` | 5 Minuten gültig | | Rücksprungadressen | 10 Stück je Eintrag | | `height` | 1 bis 20 000 px | | `Retry-After` in der Wartung | 300 Sekunden, wenn die Wartung keine eigene Zeit nennt | ## 10 Daten und Datenschutz - Das Werkzeug sieht nur das Pseudonym der Schüler:in. - `state` ist Arbeitsdaten des Werkzeugs: Es steht in keinem Export, keiner Auswertung und erreicht keine KI. Die Lehrer:in liest es nur im Modus `review`. - Es gibt **keinen Prüfdienst**: Lösungen dürfen im Werkzeug selbst liegen. Der versteckte Teil (`hidden`) ist keine Lösung im Sinne von Stundentakt und wird nur der Autor:in und dem Werkzeug in ihrer Hand gezeigt. - Zwischenstand, Antwort, Notiz und Ereignisse gehören der Person. Wer Konto, Mitglied oder Klasse löscht, löscht sie mit. - Records gehören der Person: privat, solange sie sie nicht freigibt; sie gehen mit ihrem Konto bzw. ihrem Mitglied und mit dem Werkzeug-Eintrag. Sie stehen in keinem Export, keiner Auswertung und erreichen nie eine KI oder die MCP-Schnittstelle. - Eine mitmachende Lehrer:in zählt nie als Klasse; ihre Antworten und Ereignisse fehlen in Auswertung, Export und KI. - **Auswertung je Aufgabe:** Die Lehrer:innen der Klasse (und nur sie) sehen in der Auswertung der Zuweisung unter jedem Werkzeug-Baustein, wie viele Schüler:innen etwas gemeldet haben, je Verb und je Code „x von y“ samt Anzahl und, wenn das Werkzeug `run` meldet, wie oft die Abgebenden vor ihrer Abgabe im Schnitt ausgeführt haben. Nur Zahlen und die Wörter des Werkzeugs, keine Namen; je Zuweisung, nie über Klassen hinweg. - Ereignisse haben noch keine eigene Aufbewahrungsfrist: sie gehen mit Person, Werkzeug-Eintrag, Zuweisung und Baustein. --- # Lernwerkzeuge einbinden – für Lehrer:innen und Redaktion Ein **Lernwerkzeug** ist eine Webseite eines anderen Anbieters (Übungen, Simulationen, Programmierumgebungen …), die du als Baustein in ein Medium setzt. Die Klasse arbeitet darin, Stundentakt meldet die Schüler:innen automatisch an, speichert ihren Stand und zeigt dir, was sie abgeben. Das Werkzeug sieht nur das Pseudonym einer Schüler:in, nie ihren Namen oder eine E-Mail. ## Werkzeug eintragen - **Wo:** Profilmenü → **Lernwerkzeuge** (`/tools`) → **Lernwerkzeug hinzufügen**. - **Wer:** jede Lehrer:in für sich selbst. Ein eingetragenes Werkzeug gehört dir, steht in deiner Schule (der gerade gewählten) und nur dir zur Auswahl. Werkzeuge **für alle Lehrer:innen** trägt der Betreiber ein; sie stehen in deiner Liste mit „Vom Betreiber verwaltet“. - **Angaben** (vom Anbieter des Werkzeugs): - **Name** - **Startadresse** – die Adresse, die Stundentakt öffnet; `https://`. - **Rücksprungadressen** – eine je Zeile, für die Anmeldung. - **Anzeige** – „In der Seite“ (das Werkzeug steht im Medium) oder „In eigenem Tab“ (eine Karte öffnet es in einem neuen Tab). - Nach dem Speichern steht unter der Startadresse die **Client-ID**. Die braucht der Anbieter für die Anmeldung; du kannst sie ihm schicken, sie ist kein Geheimnis. - Ändern und entfernen kann nur, wer das Werkzeug eingetragen hat (beim Betreiber-Werkzeug der Betreiber). Entfernen beendet alle Anmeldungen und löscht die freien Daten und Ereignisse des Werkzeugs; ein Baustein, der es noch nennt, zeigt es als nicht verfügbar. ## Prüfung, Sperre, AV-Vertrag - Stundentakt prüft fremde Werkzeuge nicht. Über einem Werkzeug in der Seite steht darum das Band „Externes Lernwerkzeug, nicht von Stundentakt geprüft. Gib hier nie ein Passwort ein.“, und es lädt erst, wenn die Betrachterin auf **Lernwerkzeug laden** tippt. - Hat der Betreiber mit dem Anbieter einen **Auftragsverarbeitungsvertrag** (AV-Vertrag) und das am Werkzeug bestätigt, steht dort „AV-Vertrag“; Band und Rückfrage entfallen. - **Redaktion und Betreiber** sehen unter „Alle Lernwerkzeuge“ jedes Werkzeug und können es **sperren**: Es lässt sich nicht mehr starten, offene Sitzungen enden sofort, gespeicherte Daten bleiben. Entsperren gibt es wieder frei. Den AV-Vertrag bestätigt nur der Betreiber. ## Werkzeug in ein Medium setzen 1. **Neues Medium → Lernwerkzeug** (ein Medium aus genau diesem Werkzeug) oder in einem beliebigen Medium den Baustein **Lernwerkzeug** einfügen – auch in eine Stunde eines Stoffverteilungsplans. 2. Werkzeug wählen und einen **Titel** eintragen (ohne Titel gilt der Name des Werkzeugs). Unter **Anzeige** wählst du für diese Aufgabe „In der Seite“ oder „In eigenem Tab“; ohne Wahl gilt die Anzeige des Eintrags. 3. Die **Aufgabe** schreibst du im Werkzeug selbst: Es öffnet sich unter der Auswahl im Autorenmodus und speichert, was du dort einstellst. Was es versteckt (Tests, Musterlösung), sieht nur, wer das Medium bearbeiten darf. ## Zuweisen Das Medium wie jedes andere einer Klasse **zuweisen** (mit Fenster, Frist und Modus). Erst dann öffnet die Klasse das Werkzeug. „Nur ansehen“ oder eine abgelaufene Frist sperren das Abgeben; das Werkzeug zeigt es. Ein per Link geteiltes Medium funktioniert auch: angemeldete Schüler:innen und Lehrer:innen machen dort mit, **Gäste ohne Konto** sind für ein Werkzeug nicht angemeldet und speichern nur auf ihrem Gerät. ## Was Schüler:innen sehen - „In der Seite“: das Werkzeug im Medium, darüber das Band (falls kein AV-Vertrag) mit Status und Frist. - „In eigenem Tab“: eine Karte **Lernwerkzeug öffnen**. - Sie werden ohne weitere Anmeldung erkannt, solange sie in Stundentakt angemeldet sind. Zwischenstand und Abgabe bleiben, auch auf einem anderen Gerät. - Du kannst in deiner Klasse selbst mitmachen; deine Abgaben zählen nicht zur Klasse. ## Auswertung In der Auswertung der Zuweisung steht unter jedem Werkzeug-Baustein: - **Versuche, erledigt und Durchschnittspunkte** aus den Abgaben – nur Zahlen, nie der gespeicherte Stand. - Je Schüler:in die Abgabe mit **Im Lernwerkzeug ansehen**: Das Werkzeug öffnet die Antwort zum Lesen. - **Vom Werkzeug gemeldet:** wie viele Schüler:innen etwas gemeldet haben, je Verb (z. B. `run`, `error`, `step`) und je Fehlercode „x von y“, und wenn das Werkzeug Läufe meldet, wie oft im Schnitt vor der Abgabe ausgeführt wurde. Keine Namen, nur diese Klasse. Was das Werkzeug speichert, erscheint in keinem Export und erreicht nie eine KI. Löschst du Klasse, Mitglied oder den Eintrag, gehen die Daten mit.