API-Zugriff und Scopes einrichten

Ein API-Schlüssel eignet sich für eine eigene Integration mit festem Workspace. OAuth eignet sich, wenn Benutzer einer Anwendung nach ihrer Anmeldung gezielt Zugriff geben sollen. Beide Verfahren begrenzen den Zugriff durch Scopes und die aktuellen Rechte des freigebenden Benutzers.

Die Verwaltung unter Einstellungen → API-Zugriff ist für Workspace-Administratoren mit API-Zugriffsrechten verfügbar. Benutzer können ihre eigenen OAuth-Freigaben unter Verbindungen → Meine Freigaben widerrufen.

Einen API-Schlüssel erstellen

1. Öffne API-Zugriff → API-Keys und erstelle einen Schlüssel mit eindeutigem Namen.
2. Wähle nur die benötigten Scopes. Für den ersten Lesetest genügen connection:verify und agents:read.
3. Wähle eine Gültigkeit: 30 Tage, 90 Tage, ein Jahr, ein eigenes zukünftiges Datum oder ausdrücklich ohne Ablaufdatum. Bevorzuge eine begrenzte Laufzeit.
4. Kopiere den vollständigen Schlüssel aus der einmaligen Anzeige und hinterlege ihn im geschützten Zugangsdaten-Speicher deiner Anwendung.
5. Sende ihn im Header Authorization: Bearer <API_KEY> an die REST-API.

Rotieren erzeugt einen neuen Schlüssel und macht den bisherigen sofort ungültig. Name, Scopes und Ersteller bleiben erhalten. Widerrufen sperrt den Schlüssel dauerhaft. Für andere Scopes legst du einen neuen Schlüssel an. API-Schlüssel benötigen keine Callback-URL und funktionieren unabhängig davon, ob OAuth verfügbar ist.

Eine OAuth-Anwendung registrieren

1. Öffne den Bereich OAuth unter API-Zugriff und wähle Anwendung anlegen.
2. Vergib einen Namen und hinterlege 1 bis 10 exakte HTTPS-Callback-URLs deiner Anwendung, ohne Platzhalter oder Fragmente.
3. Wähle die erlaubten Scopes und speichere die Anwendung.
4. Übernimm die Client-ID sowie die Werte aus OAuth einrichten: Autorisierungs-URL, Token-URL, Issuer und gegebenenfalls Resource.

Die Anwendung ist an diesen Workspace gebunden. Sie nutzt Authorization Code mit PKCE S256, ohne Client-Secret. Jede gespeicherte Änderung der Registrierung sowie ihre Deaktivierung widerruft bestehende Freigaben und Tokens; danach ist eine neue Anmeldung nötig.

OAuth in deiner Anwendung verwenden

1. Erzeuge für jede Anmeldung einen neuen PKCE-Verifier, dessen S256-Challenge und einen zufälligen state.
2. Öffne die Autorisierungs-URL mit response_type=code, client_id, exakter redirect_uri, durch Leerzeichen getrennten scope-Werten, code_challenge, code_challenge_method=S256 und state.
3. Der Benutzer meldet sich bei Nuvoca an, prüft Workspace und Rechte und stimmt zu oder lehnt ab.
4. Prüfe am Callback state. Tausche den Code einmalig per formcodiertem POST an die Token-URL mit grant_type=authorization_code, client_id, redirect_uri, code und code_verifier aus.
5. Speichere Access- und Refresh-Token geschützt. Sende das Access-Token als Bearer-Header an die REST-API.

Für REST ist die Resource optional. Wenn du sie angibst, muss sie exakt dem angezeigten REST-Wert entsprechen: Issuer plus /api/external. MCP verwendet eine andere Resource, Issuer plus /mcp. Tokens sind zwischen diesen Zugängen nicht austauschbar. Client Credentials, DCR und OIDC sind keine unterstützten Anmeldeverfahren dieses Zugangs.

Tokens erneuern

Ein Access-Token gilt fünf Minuten. Zum Erneuern sendest du einen formcodierten POST an die Token-URL mit grant_type=refresh_token, client_id und dem aktuellen refresh_token, ohne Client-Secret.

Speichere beide neuen Tokens gemeinsam und verwende den vorherigen Refresh-Token nicht erneut. Serialisiere Erneuerungen: Die Wiederverwendung eines bereits verbrauchten Refresh-Tokens widerruft die gesamte Freigabe. Eine Freigabe gilt höchstens 24 Stunden ab ihrer ursprünglichen Autorisierung; Refresh verlängert diese Frist nicht. Danach, nach Widerruf oder fehlgeschlagenem Refresh ist eine neue Anmeldung nötig.

Scopes auswählen

Scope	Erlaubt
connection:verify	Gebundenen Workspace und freigegebene Rechte prüfen
agents:read	Agents auflisten
agents:configuration:read	Agent-Konfiguration einschließlich Prompts und Auswahlkatalogen lesen
agents:write	Agents erstellen und konfigurieren
flows:read / flows:write	Agentic Flows und Katalog lesen / Flows verwalten
tools:read / tools:write	Toolkonfiguration und Kataloge lesen / Agent-Tools verwalten
knowledge-bases:read / knowledge-bases:write	Knowledge Bases lesen / verwalten
documents:read / documents:write	Dokumentmetadaten lesen / Dokumente hinzufügen und löschen
pre-processing:read / pre-processing:write	Pre-Processing-Profile und Variablen lesen / Profile konfigurieren
post-processing:read / post-processing:write	Post-Processing-Profile und Variablen lesen / Profile konfigurieren
phone-numbers:read / phone-numbers:write	Vorhandene Rufnummern lesen / Standardzuweisungen verwalten
call-summaries:read	Gespeicherte Zusammenfassungen und Anrufdaten einschließlich Rufnummern lesen

Schreibscopes enthalten keine Lesescopes. Für einen Bearbeitungsablauf wählst du beide. Ein Knowledge-Base-Scope ersetzt kein Dokumentrecht. Credential-Kataloge setzen zusätzlich deine aktuellen Leserechte für Zugangsdaten voraus.

Bestehende Schlüssel und Freigaben erhalten neue Scopes nicht automatisch. Der Zugriff bleibt an einen Workspace und die aktuellen Benutzerrechte gebunden, auch wenn ein Token noch nicht abgelaufen ist.

Zugriff entziehen und Zugangsdaten schützen

Widerrufe OAuth unter Verbindungen → Meine Freigaben, MCP-Freigaben als berechtigter Administrator auch unter MCP im Tenant. Schlüssel widerrufst du unter API-Keys. Entfernen oder Vergessen eines Zugangs nur im Client ersetzt diesen Widerruf nicht.

Verwende keine Tokens in URLs, Quellcode, Screenshots oder Protokollen. Eine MFA-Wiederherstellung sperrt vorhandene API-Schlüssel und OAuth-/MCP-Freigaben nicht automatisch. Widerrufe betroffene Maschinenzugänge bei einem Sicherheitsvorfall gesondert.