# Integrationsschlüssel

Angemeldete Webnutzer finden unter **API-Schlüssel** eine eigene Verwaltungsseite.
Programmname und mindestens ein Projekt auswählen, dann den Schlüssel erstellen.
**Anzeigen** ruft ihn bei Bedarf erneut ab; **Verbergen** entfernt ihn aus dem
Eingabefeld. **Kopieren** verwendet die Zwischenablage (HTTPS oder localhost).
**Widerrufen** sperrt ihn sofort für nachfolgende API-Anfragen. Bereits laufende
Anfragen werden dadurch nicht abgebrochen. Ein widerrufener Schlüssel wird nicht
mehr angezeigt; für einen Ersatz einen neuen Schlüssel erstellen.

Alle angemeldeten menschlichen Nutzer haben dieselben Verwaltungsrechte.
Maschinenzugänge können weder Schlüssel verwalten noch andere Schlüssel anzeigen.
Webmutationen einschließlich Anzeigen benötigen die vorhandene CSRF-Absicherung.

Das aufrufende Programm sendet `Authorization: Bearer <Schlüssel>` an die
Übergabe-API. Neue Schlüssel erlauben Auftragsübergabe einschließlich Rückgaben
und lesenden Zugriff auf die ausgewählten Projekte. Sie erlauben keine
Betriebssteuerung oder Beantwortung menschlicher Testanfragen. Zugriff auf weitere
Projekte erfordert einen neuen Schlüssel. Bestehende env-basierte Integrationen
bleiben unverändert nutzbar und erscheinen nicht in der SQLite-Schlüsselliste.

## Speicherung und Sicherung

- SQLite unter `<workspace>/runtime/integrations/keys.sqlite3` speichert Metadaten,
  SHA-256-Prüfwerte und mit Fernet authentifiziert verschlüsselte Schlüssel.
- Der separate Serverschlüssel entsteht beim ersten Erstellen automatisch unter
  `<workspace>/runtime/integration-secrets/master.key`, Dateimodus 0600.
  Nutzerkonten und ihre root-verwaltete SQLite-Datei werden nicht verändert.
- Mit `VIANO_INTEGRATION_KEY_FILE` kann die API stattdessen eine separate
  Schlüsseldatei verwenden. Vorhandene Dateien müssen einen gültigen Fernet-Key
  enthalten und für den API-Dienst lesbar sein; fehlt die Datei beim ersten
  Erstellen, muss der Dienst sie im gewählten Verzeichnis anlegen dürfen.
- SQLite und Serverschlüssel getrennt geschützt sichern. Das Laufzeitverzeichnis
  enthält damit dauerhaft notwendige Integrationsdaten und darf bei einer
  Bereinigung von Sessions nicht pauschal gelöscht werden. Unter Windows passende
  Dateisystem-ACLs verwenden; POSIX-Modusbits ersetzen dort keine ACLs.
- Geht der Serverschlüssel verloren oder wird er unpassend ausgetauscht, können
  Schlüssel nicht mehr angezeigt werden. Das System ersetzt ihn bei bestehenden
  Einträgen nicht stillschweigend. Vorhandene Schlüssel können anhand ihrer
  Prüfwerte weiterhin authentifiziert und über die Weboberfläche widerrufen werden.
  Zur Wiederherstellung die richtige Schlüsseldatei aus der Sicherung zurückspielen.

Nach einem Update die API-Abhängigkeiten neu installieren (`.[api]` umfasst jetzt
`cryptography`) und den API-Dienst neu starten. Eine Datenbankmigration per Hand
ist nicht nötig. Keine Änderung oder Neueingabe des Gemini-Schlüssels erforderlich.