OAuth-Einrichtung¶

OAuth-Zugangsdaten

OAuth erlaubt API-Tools, externe Dienste zu nutzen, ohne Secrets in Prompts zu speichern. Fordern Sie nur nötige Scopes an und testen Sie die Credential vor Live-Nutzung.

Eine gute OAuth-Konfiguration ist autorisiert, eng berechtigt, getestet und leicht widerrufbar.

OAuth 2.0 Zugangsdaten ermöglichen API-Tools die Authentifizierung bei externen Diensten. Nuvoca unterstützt zwei OAuth Grant Types für unterschiedliche Integrationsfälle.

Unterstützte Grant Types¶

Grant Type	Einsatz	Nutzerinteraktion	Beispiele
Client Credentials	Server-zu-Server-Authentifizierung	Keine	Stripe API, Twilio API, interne APIs
Authorization Code + PKCE	Zugriff auf Nutzerdaten mit Zustimmung	Einmalig erforderlich	Google Calendar, Microsoft Graph, GitHub

Wann welchen Flow nutzen?

Client Credentials nutzen Sie, wenn ein Tool auf eigene Service-Daten zugreift und keine Nutzerzustimmung nötig ist.
Authorization Code + PKCE nutzen Sie, wenn ein externer Dienst eine Nutzerfreigabe verlangt, zum Beispiel Google, Microsoft oder GitHub.

Wie OAuth in Nuvoca funktioniert¶

Client Credentials Flow¶

sequenceDiagram
    participant Agent as Voice Agent
    participant Platform as Nuvoca Platform
    participant API as External API

    Agent->>Platform: API-Tool mit OAuth ausführen
    Platform->>API: Access Token anfordern
    API-->>Platform: Access Token zurückgeben
    Platform->>API: API-Aufruf mit Bearer Token
    API-->>Platform: Daten zurückgeben
    Platform-->>Agent: Ergebnis zurückgeben

Ablauf:

Konfiguration: OAuth Client ID und Secret werden in Settings → Credentials gespeichert.
Token Request: Die Plattform fordert ein Access Token über Client ID und Secret an.
Caching: Das Access Token wird für seine Laufzeit zwischengespeichert.
API-Aufruf: Nuvoca ruft die API mit Authorization: Bearer <token> auf.
Automatische Erneuerung: Wenn das Token abläuft, wird ein neues Token geholt.

Authorization Code + PKCE Flow¶

sequenceDiagram
    participant User as Nutzer
    participant Platform as Nuvoca Platform
    participant Provider as OAuth Provider
    participant Agent as Voice Agent

    User->>Platform: "Authorize" klicken
    Platform->>Platform: PKCE Code Verifier/Challenge erzeugen
    Platform->>Provider: Authorization Popup öffnen
    Provider->>User: Consent Screen anzeigen
    User->>Provider: Berechtigungen erteilen
    Provider->>Platform: Redirect mit Authorization Code
    Platform->>Provider: Code gegen Tokens tauschen
    Provider-->>Platform: Access + Refresh Tokens zurückgeben
    Platform->>Platform: Refresh Token sicher speichern

    Agent->>Platform: API-Tool mit OAuth ausführen
    Platform->>Provider: API-Aufruf mit Access Token
    Provider-->>Platform: Daten zurückgeben
    Platform-->>Agent: Ergebnis zurückgeben

Ablauf:

Konfiguration: OAuth-Konfiguration mit Authorization URL, Token URL und Redirect URI erstellen.
Autorisierung: Authorize öffnet ein Popup beim OAuth-Anbieter.
Nutzerzustimmung: Der Nutzer erteilt die angeforderten Berechtigungen.
Token Exchange: Nuvoca tauscht den Authorization Code gegen Access und Refresh Tokens.
Speicherung: Das Refresh Token wird sicher gespeichert, Access Tokens werden gecacht.
API Calls: API-Tools nutzen das gecachte Access Token.
Auto Refresh: Nach Ablauf des Access Tokens wird über das Refresh Token ein neues geholt.
Re-Autorisierung: Wenn das Refresh Token abläuft oder widerrufen wird, muss erneut autorisiert werden.

OAuth-Konfiguration erstellen¶

Schritt 1: Credentials öffnen¶

Öffnen Sie im Dashboard Settings → Credentials.

OAuth Credentials Empty

Hier sehen Sie alle OAuth-Konfigurationen Ihres Tenants.

Schritt 2: Konfiguration hinzufügen¶

Klicken Sie Add OAuth Configuration, um den Dialog zu öffnen.

OAuth Configuration Dialog

Schritt 3: Grant Type wählen¶

Wählen Sie zuerst den passenden Grant Type.

Einstellung	Beschreibung
Grant Type	Client Credentials für Server-zu-Server oder Authorization Code (PKCE) für nutzerbezogenen Zugriff

Schritt 4: Gemeinsame Einstellungen konfigurieren¶

Diese Felder sind für beide Grant Types relevant:

Feld	Beschreibung	Beispiel
Configuration Name	Anzeigename für diese OAuth-Konfiguration	`Google Calendar API`
Client ID	OAuth Client ID des Anbieters	`your-app.apps.googleusercontent.com`
Token URL	OAuth Token-Endpunkt	`https://oauth2.googleapis.com/token`
Scopes	Leerzeichengetrennte Berechtigungen	`https://www.googleapis.com/auth/calendar.readonly`
Header Prefix	Präfix für den Authorization Header	`Bearer`

Schritt 5: Grant-spezifische Einstellungen konfigurieren¶

Für Client Credentials¶

Feld	Beschreibung	Beispiel
Client Secret	OAuth Client Secret	`GOCSPX-abc123xyz...`

Für Authorization Code + PKCE¶

Feld	Beschreibung	Beispiel
Client Secret	Optional bei PKCE, manche Anbieter verlangen es trotzdem	leer lassen oder Anbieter-Secret
Authorization URL	OAuth Authorization-Endpunkt	`https://accounts.google.com/o/oauth2/v2/auth`
Redirect URI	Muss exakt beim Anbieter registriert sein	`https://your-platform.com/oauth/callback`

Redirect URI muss exakt passen

Die Redirect URI muss exakt mit der beim Anbieter registrierten URI übereinstimmen. Achten Sie auf Protokoll, Domain, Pfad und abschließende Slashes.

PKCE Client Secret

Bei reinen PKCE-Flows ist das Client Secret oft optional. Einige Anbieter empfehlen es trotzdem für vertrauliche Clients. Prüfen Sie die Dokumentation des jeweiligen Anbieters.

Vollständiges Beispiel: Google Calendar API (PKCE)¶

Für Google Calendar nutzen Sie Authorization Code + PKCE, weil Google für Kalenderdaten eine Nutzerzustimmung verlangt und Client Credentials für Nutzerdaten nicht geeignet sind.

Schritt 1: Google Cloud Projekt erstellen¶

Öffnen Sie die Google Cloud Console.
Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes Projekt.
Öffnen Sie APIs & Services → Library.
Suchen Sie nach Google Calendar API und klicken Sie Enable.

Schritt 2: OAuth Credentials erstellen¶

Öffnen Sie APIs & Services → Credentials.
Klicken Sie Create Credentials → OAuth client ID.
Wählen Sie als Application type: Web application.
Setzen Sie einen Namen, zum Beispiel Nuvoca Integration.
Fügen Sie unter Authorized redirect URIs die Callback URL Ihrer Plattform hinzu:

https://your-platform.com/oauth/callback

Klicken Sie Create.

Schritt 3: Zugangsdaten kopieren¶

Notieren Sie:

Client ID: your-app.apps.googleusercontent.com
Client Secret: GOCSPX-abc123xyz... (bei PKCE optional, aber bei Google häufig empfohlen)

Schritt 4: In Nuvoca konfigurieren¶

Feld	Wert
Configuration Name	Google Calendar API
Grant Type	Authorization Code (PKCE)
Client ID	`your-app.apps.googleusercontent.com`
Client Secret	Ihr Google Client Secret oder leer
Authorization URL	`https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent`
Token URL	`https://oauth2.googleapis.com/token`
Redirect URI	`https://your-platform.com/oauth/callback`
Scopes	`https://www.googleapis.com/auth/calendar.readonly`

Häufige Google Calendar Scopes

https://www.googleapis.com/auth/calendar.readonly — Kalender nur lesen
https://www.googleapis.com/auth/calendar — Kalender lesen und schreiben
https://www.googleapis.com/auth/calendar.events.readonly — Events nur lesen
https://www.googleapis.com/auth/calendar.events — Events lesen und schreiben

Schritt 5: OAuth-Konfiguration autorisieren¶

Nach dem Speichern:

Suchen Sie die neue OAuth-Konfiguration in der Liste.
Öffnen Sie das Menü ⋮ und wählen Sie PKCE Authorization.
Ein Popup öffnet die Zustimmung beim Anbieter.
Melden Sie sich mit dem Google-Konto an und erlauben Sie die angeforderten Scopes.
Nach erfolgreicher Zustimmung schließt sich das Popup.
Nuvoca zeigt eine Erfolgsmeldung.

Refresh Token

Für Google sollte die Authorization URL access_type=offline&prompt=consent enthalten. Ohne diese Parameter gibt Google häufig nur ein kurzlebiges Access Token zurück und kein Refresh Token.

Vollständiges Beispiel: Stripe API (Client Credentials)¶

Für serverseitige API-Zugriffe nutzen Sie Client Credentials, wenn kein Nutzer-Consent erforderlich ist.

In Nuvoca konfigurieren¶

Feld	Wert
Configuration Name	Stripe API
Grant Type	Client Credentials
Client ID	`sk_test_your_secret_key`
Client Secret	derselbe Secret Key oder das vom Anbieter verlangte Secret
Token URL	`https://api.stripe.com/v1/oauth/token`
Scopes	leer lassen, falls der Anbieter keine Scopes nutzt

Anbieterlogik prüfen

Einige Anbieter verwenden API Keys statt eines klassischen OAuth Client-Credentials-Flows. Nutzen Sie dieses Beispiel als Strukturhilfe und prüfen Sie die Authentifizierungsdokumentation des jeweiligen Dienstes.

OAuth in API-Tools nutzen¶

Wenn die OAuth-Konfiguration gespeichert ist, können API-Tools sie verwenden:

Öffnen Sie beim Agenten Tools.
Klicken Sie Create Tool und wählen Sie HTTP API request.
Konfigurieren Sie das API-Tool, zum Beispiel:
Tool name: google_calendar_lookup
Execution description: Nutze dieses Tool, wenn der Anrufer nach Terminen oder Verfügbarkeit fragt.
HTTP method: GET
Request URL: https://www.googleapis.com/calendar/v3/calendars/primary/events
Wählen Sie unter Authentication die gespeicherte OAuth-Konfiguration.
Ergänzen Sie Query Parameter wie timeMin oder maxResults, falls nötig.
Speichern und testen Sie das Tool.

OAuth-Konfigurationen verwalten¶

OAuth-Konfiguration testen¶

Aus der Credential-Liste:

Öffnen Sie das Menü ⋮ neben einer Konfiguration.
Wählen Sie Test.
Nuvoca versucht, ein neues Access Token zu holen.
Erfolg bedeutet, dass die Konfiguration grundsätzlich funktioniert.

Bei PKCE-Konfigurationen testet dies den Refresh-Token-Flow. Wenn kein Refresh Token vorhanden ist, müssen Sie zuerst autorisieren.

Gecachte Tokens invalidieren¶

Wenn Sie erzwingen möchten, dass beim nächsten API-Aufruf ein neues Token geholt wird:

Öffnen Sie ⋮ → Invalidate Token.
Das gecachte Access Token wird gelöscht.
Der nächste API-Aufruf fordert ein frisches Token an.

Autorisierung widerrufen¶

Wenn eine erneute Autorisierung nötig ist:

Öffnen Sie ⋮ → Revoke Credentials.
Nuvoca löscht Refresh Token und gecachtes Access Token.
Der nächste Zugriff erfordert erneut PKCE Authorization.

OAuth-Konfiguration bearbeiten¶

Öffnen Sie ⋮ → Edit.
Ändern Sie Felder wie Scopes, Token URL oder Client Secret.
Beim Speichern wird das gecachte Token invalidiert.

OAuth-Konfiguration löschen¶

Öffnen Sie ⋮ → Delete.
Bestätigen Sie die Löschung.
Zugehörige Tokens werden entfernt.
API-Tools, die diese Konfiguration nutzen, schlagen danach fehl, bis sie angepasst werden.

Troubleshooting¶

Client-Credentials-Probleme¶

Problem	Symptom	Lösung
Invalid Client	401 oder `invalid_client`	Client ID und Secret prüfen
Falsche Token URL	Verbindungsfehler oder 404	Token-Endpunkt des Anbieters prüfen
Fehlende Scopes	403 oder `insufficient_permissions`	Benötigte Scopes ergänzen

Authorization Code + PKCE Probleme¶

Problem	Symptom	Lösung
Redirect URI Mismatch	`redirect_uri_mismatch`	Redirect URI in Nuvoca und beim Anbieter exakt angleichen
Popup blockiert	Beim Klick auf Authorize passiert nichts	Popups für die Plattform erlauben
Authorization abgelaufen	Token Fetch schlägt nach einiger Zeit fehl	PKCE Authorization erneut durchführen
Invalid State	`Invalid state parameter`	Autorisierung erneut starten; der Flow ist wahrscheinlich abgelaufen

Häufige OAuth Provider Settings¶

Anbieter	Authorization URL	Token URL
Google	`https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent`	`https://oauth2.googleapis.com/token`
GitHub	`https://github.com/login/oauth/authorize`	`https://github.com/login/oauth/access_token`
Microsoft	`https://login.microsoftonline.com/common/oauth2/v2.0/authorize`	`https://login.microsoftonline.com/common/oauth2/v2.0/token`
Slack	`https://slack.com/oauth/v2/authorize`	`https://slack.com/api/oauth.v2.access`

Google-spezifische Parameter

Für Google sollten Sie immer access_type=offline&prompt=consent in der Authorization URL setzen. Nur so erhalten Sie zuverlässig ein Refresh Token für langfristigen Zugriff.

Sicherheitsregeln¶

Nutzen Sie PKCE, wenn der Anbieter es unterstützt.
Fordern Sie nur die minimal nötigen Scopes an.
Rotieren Sie Client Secrets gemäß Ihrer Sicherheitsrichtlinie.
Prüfen Sie regelmäßig, welche OAuth-Konfigurationen noch genutzt werden.
Widerrufen oder löschen Sie Credentials, die nicht mehr gebraucht werden.
Nutzen Sie in Produktion nur HTTPS Redirect URIs.
Speichern Sie Client Secrets nie in Prompts, Browsercode oder Logs.

Weiterführende Seiten