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 typische OAuth-Flows für serverseitige und nutzerbezogene Integrationen.

Unterstützte Grant Types

Grant Type	Einsatz	Nutzerinteraktion	Beispiele
Client Credentials	Server-zu-Server	Keine	Interne APIs, Service-Accounts
Authorization Code + PKCE	Zugriff auf Nutzerdaten	Einmalige Zustimmung	Google Calendar, Microsoft Graph, GitHub

Wann welchen Flow nutzen?

• Client Credentials: für eigene Service-Daten ohne Nutzerzustimmung.
• Authorization Code + PKCE: wenn ein Nutzer Zugriff erlauben muss.

Client Credentials Flow

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

    Agent->>Platform: Execute API tool with OAuth
    Platform->>API: Request access token
    API-->>Platform: Return access token
    Platform->>API: API call with Bearer token
    API-->>Platform: Return data
    Platform-->>Agent: Return response

Ablauf:

1. OAuth-Konfiguration in den Credentials speichern.
2. Plattform fordert Access Token an.
3. Token wird für die Laufzeit gecacht.
4. API-Aufruf nutzt Authorization: Bearer <token>.
5. Neues Token wird geholt, wenn das alte abläuft.

Authorization Code + PKCE

Dieser Flow ist geeignet, wenn ein externer Anbieter eine Nutzerfreigabe verlangt.

Ablauf:

1. OAuth-Konfiguration mit Authorization URL und Redirect URI erstellen.
2. Authorize öffnet den Anbieter in einem Popup.
3. Nutzer erteilt Zustimmung.
4. Plattform tauscht Code gegen Tokens.
5. Refresh Token wird sicher gespeichert.
6. API-Tools nutzen gecachte Access Tokens.
7. Bei Ablauf wird automatisch erneuert.

OAuth-Konfiguration erstellen

Schritt 1: Credentials öffnen

Öffnen Sie Settings → Credentials.

Schritt 2: Konfiguration hinzufügen

Klicken Sie Add OAuth Configuration.

Schritt 3: Grant Type wählen

Wählen Sie den passenden Grant Type.

Schritt 4: Gemeinsame Einstellungen

Feld	Beschreibung	Beispiel
Configuration Name	Anzeigename	Google Calendar API
Client ID	OAuth Client ID	your-app.apps.googleusercontent.com
Token URL	Token-Endpunkt	https://oauth2.googleapis.com/token
Scopes	Berechtigungen	calendar.readonly
Header Prefix	Meist Bearer	Bearer

Grant-spezifische Einstellungen

Für Client Credentials brauchen Sie meist ein Client Secret.

Für Authorization Code + PKCE brauchen Sie zusätzlich:

• Authorization URL
• Redirect URI
• je nach Anbieter optional Client Secret

Redirect URI muss exakt passen

Die Redirect URI muss exakt mit der beim Anbieter registrierten URI übereinstimmen.

Google Calendar Beispiel

Typische Werte:

Feld	Wert
Configuration Name	Google Calendar API
Grant Type	Authorization Code (PKCE)
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	gewünschte Calendar Scopes

Google Refresh Token

Für Google sollten access_type=offline&prompt=consent in der Authorization URL stehen, damit ein Refresh Token zurückgegeben wird.

OAuth in API-Tools nutzen

1. Agenten-Tools öffnen.
2. HTTP API request erstellen.
3. API konfigurieren.
4. Unter Authentication die gespeicherte OAuth-Konfiguration auswählen.
5. Tool speichern und testen.

Verwaltung

Sie können OAuth-Konfigurationen testen, Tokens invalidieren, Autorisierung widerrufen, bearbeiten oder löschen.

Troubleshooting

Problem	Symptom	Lösung
Invalid Client	401 oder invalid_client	Client ID/Secret prüfen
Falsche Token URL	Verbindungsfehler oder 404	Token-Endpunkt prüfen
Fehlende Scopes	403	Benötigte Scopes ergänzen
Redirect mismatch	Anbieterfehler	Redirect URI exakt angleichen
Popup blockiert	Autorisierung öffnet nicht	Popups erlauben

Sicherheitsregeln

• Scopes minimal halten.
• Secrets regelmäßig rotieren.
• Unbenutzte Credentials löschen oder widerrufen.
• HTTPS für Redirect URIs nutzen.
• Client Secrets nie in Prompts, Browsercode oder Logs speichern.