Zum Inhalt

API-Aufruf von BusinessGPT per OAuth2 (Client Credentials)

Übersicht

Diese Anleitung beschreibt Schritt für Schritt:

  1. Welche technischen Voraussetzungen für den API-Zugriff auf BusinessGPT nötig sind
  2. Wie Sie in Microsoft Entra ID (Azure AD) eine API-App-Registrierung anlegen
  3. Wie Sie per OAuth2 Client Credentials ein Access Token in einem API-Tool (z. B. Postman) abrufen
  4. Wie Sie damit einen ersten Testaufruf an BusinessGPT durchführen

Wichtiger Hinweis

Alle in dieser Anleitung genannten URLs, IDs, Modell-IDs und Namen sind Beispiele.
In Ihrer Umgebung müssen Sie immer die konkreten Werte aus Ihrem Tenant und Ihrer BusinessGPT-Instanz verwenden.

1. Voraussetzungen

Bevor Sie starten, stellen Sie bitte sicher, dass:

  • Sie Zugriff auf das Azure-Portal (Microsoft Entra ID / Azure AD) haben
  • Ihnen bekannt ist, welche App-Registrierung Ihre „normale“ BusinessGPT-Anwendung repräsentiert (z. B. mit einem Namen wie „customer“ – nur ein Beispiel)
  • Eine Person mit Adminrechten in Ihrem Tenant bei Bedarf einmalig den Admin-Consent erteilen kann (siehe Schritt 2.6)
  • Sie ein API-Tool verwenden, z. B.:
    • Postman
    • Rapid API Client (Visual Studio Code Extension)
    • Ein anderes REST-Client-Tool Ihrer Wahl

2. Entra ID: Zusätzliche App-Registrierung für den API-Zugriff anlegen

Diese App-Registrierung fungiert als „technischer Benutzer“, über den sich Ihr System gegenüber BusinessGPT authentifiziert.

2.1. Neue App-Registrierung erstellen

  1. Öffnen Sie das Azure-Portal, z. B. über:
    https://portal.azure.com (Beispiel-URL)
  2. Navigieren Sie zu:
    Microsoft Entra ID → App-Registrierungen.
  3. Klicken Sie oben auf „Neue Registrierung“.
  4. Geben Sie einen aussagekräftigen Namen ein, z. B.:
  5. BusinessGPT-API-Client
    (Dies ist nur ein Beispielname. Verwenden Sie einen Namen, der in Ihrer Umgebung sinnvoll ist.)
  6. Wählen Sie als unterstützte Kontotypen in der Regel:
  7. „Nur Konten in diesem Organisationsverzeichnis“
    (Standard für interne Unternehmenslösungen)
  8. Klicken Sie auf „Registrieren“.

App-Registrierung

Ergebnis:

  • Sie sehen jetzt die Detailseite der neuen App-Registrierung.
  • Notieren Sie sich die Application (client) ID – diese wird später im API-Tool als Client ID benötigt.

App-Registrierung

2.2. Client-Secret (Passwort) erstellen

Damit sich diese App-Registrierung später gegenüber der Microsoft Identity Plattform authentifizieren kann, benötigen Sie ein Client Secret (ein geheimes Passwort).

  1. Öffnen Sie in der neu angelegten App-Registrierung den Menüpunkt
    „Zertifikate & Geheimnisse“.
  2. Unter „Clientgeheimnisse“ klicken Sie auf „Neues Clientgeheimnis“. App-Registrierung
  3. Geben Sie eine Beschreibung ein, z. B.:
  4. Secret für BusinessGPT-API-Zugriff (Beispiel)
  5. Wählen Sie eine Gültigkeitsdauer (z. B. 6 oder 12 Monate – je nach Sicherheitsrichtlinie in Ihrem Unternehmen).
  6. Klicken Sie auf „Hinzufügen“. App-Registrierung
  7. Kopieren Sie den Wert des Client Secrets direkt nach dem Anlegen und speichern Sie ihn sicher, z. B. in einem Passwortmanager. App-Registrierung

Wichtiger Hinweis

Der Wert des Client Secrets wird nach dem Schließen der Seite nicht mehr vollständig angezeigt. Wenn er verloren geht, muss ein neues Secret erstellt werden.

2.3. Token-Endpunkt (Access Token URL) ermitteln

Diese URL benötigt Ihr API-Tool, um das OAuth2-Token abzurufen.

  1. Klicken Sie in der gleichen App-Registrierung oben auf „Endpunkte“.
  2. Suchen Sie den Eintrag „OAuth 2.0 token endpoint (v2)“.
  3. Kopieren Sie die dort angegebene URL, z. B.:
https://login.microsoftonline.com/<TENANT-ID>/oauth2/v2.0/token
  • <TENANT-ID> ist ein Platzhalter für Ihre Tenant-ID.

App-Registrierung

2.4. Zusätzliche App mit der „normalen“ BusinessGPT-App verknüpfen

Nun legen Sie fest, welche Rolle diese neue API-App in Bezug auf Ihre BusinessGPT-Anwendung hat.

Wichtiger Hinweis

Die Bezeichnungen der Menüpunkte können je nach Konfiguration und Sprache leicht variieren. Nutzen Sie bei Bedarf die Suchfunktion im Azure-Portal.

2.4.1. „Normale“ BusinessGPT-App-Registrierung öffnen

  1. Wechseln Sie im Azure-Portal wieder zu „App-Registrierungen“.
  2. Suchen Sie nach der App-Registrierung, die Ihre BusinessGPT-Hauptanwendung repräsentiert.
  3. Beispiel: customer (dies ist nur ein Platzhaltername).
  4. Öffnen Sie diese App-Registrierung.

2.4.2. Berechtigungen / Rollen für den API-Client einrichten

Je nach Konfiguration Ihrer Umgebung finden Sie die relevanten Einstellungen typischerweise in den Bereichen:

  • „API-Berechtigungen“
  • oder „Unternehmensanwendungen (Enterprise Applications)“ → „Benutzer und Gruppen“ / „Rollen“

App-Registrierung

Typisches Vorgehen:

  1. Fügen Sie die neue API-App-Registrierung (z. B. BusinessGPT-API-Client) als berechtigte Anwendung hinzu.
  2. Weisen Sie dieser App die Rolle api zu.

App-Registrierung

Wichtiger Hinweis

Stellen Sie sicher, dass der API-Client die Rolle api erhält, damit ein Zugriff auf BusinessGPT per API möglich ist.

Rolle zuweisen

2.5. Optional: Separaten API-Client mit Admin-Rechten einrichten

Falls Sie ein System haben, das weitere administrative Aktionen via API durchführen soll (z. B. Konfigurationen, Management-Funktionen), bietet es sich an, eine zweite API-App-Registrierung mit einer admin-Rolle zu verwenden.

Vorgehen:

  1. Wiederholen Sie die Schritte 2.1 bis 2.3 für eine zweite App-Registrierung, z. B. mit dem Namen:
  2. BusinessGPT-API-Admin (Beispiel)
  3. Weisen Sie dieser App in der BusinessGPT-Haupt-App-Registrierung statt api die Rolle admin zu.

Wichtiger Hinweis

Verwenden Sie separate API-Clients für api- und admin-Berechtigungen, um das Prinzip der minimalen Rechte (Least Privilege) umzusetzen.

Viele Berechtigungen werden erst wirksam, wenn eine Administratorin oder ein Administrator im Tenant die Zustimmung (Admin Consent) erteilt hat.

  1. Öffnen Sie die „normale“ BusinessGPT-App-Registrierung.
  2. Wechseln Sie in den Bereich „API-Berechtigungen“ (oder einen ähnlich benannten Bereich).
  3. Klicken Sie auf „Admin consent erteilen“, „Zustimmung erteilen“ o. ä.
  4. Folgen Sie dem Dialog und bestätigen Sie die Freigabe.

App-Registrierung App-Registrierung

Kontrolle:

  • Unter „Benutzer und Gruppen“ bzw. in den Unternehmensanwendungen sollte die neue API-App-Registrierung als Service Principal sichtbar sein.
  • Prüfen Sie, ob die erwartete Rolle (api) zugewiesen wurde.

App-Registrierung

3. OAuth2-Konfiguration im API-Tool (z. B. Postman)

Nachdem die Entra-ID-Konfiguration abgeschlossen ist, können Sie ein Access Token abrufen und API-Aufrufe an BusinessGPT senden.

3.1. Beispielkonfiguration in Postman

(alle Werte sind Platzhalter und müssen angepasst werden)

  1. Erstellen Sie in Postman eine neue Collection oder einen neuen Request.
  2. Wechseln Sie im Request auf den Tab „Authorization“.
  3. Wählen Sie als Typ: OAuth 2.0.

  4. Füllen Sie die Felder wie folgt (Beispiele):

  5. Grant Type: Client Credentials

  6. Access Token URL:
    https://login.microsoftonline.com/<TENANT-ID>/oauth2/v2.0/token
    Ersetzen Sie <TENANT-ID> durch Ihre tatsächliche Tenant-ID.
  7. Client ID:
    Die Application (client) ID Ihrer API-App-Registrierung, z. B.:
    00000000-0000-0000-0000-000000000000 (Beispielwert)
  8. Client Secret:
    Der zuvor erzeugte Secret-Wert, z. B.:
    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (Beispiel)
  9. Scope:
    Typische Form, abhängig von Ihrer Konfiguration:
    api://<APP-REG-CLIENT-ID>/.default
    oder
    <APP-REG-CLIENT-ID>/.default
    Ersetzen Sie <APP-REG-CLIENT-ID> durch die Application (client) ID Ihrer „normalen“ BusinessGPT-App-Registrierung.

  10. Client Authentication:
    Wählen Sie z. B. „Send as Basic Auth header“ oder „In Request Body“ – beide Methoden werden von der Microsoft Identity Plattform in der Regel unterstützt.

  11. Klicken Sie auf „Get New Access Token“ (oder einen entsprechend benannten Button).

Postman Postman

Wenn alle Angaben korrekt sind, wird Ihnen ein Access Token angezeigt, das Sie speichern und für Ihre Requests verwenden können.

Wichtiger Hinweis

Wenn die Token-Anforderung fehlschlägt (z. B. Fehler 401/403), prüfen Sie bitte: Tenant-ID, Client ID, Client Secret, Scope und ob der Admin-Consent bereits erteilt wurde.

4. Ersten Testaufruf an BusinessGPT senden

4.1. Request-URL (Beispiel)

https://customer.businessgpt.telekom.net/api/v2/chat/completions

Wichtiger Hinweis

Diese URL ist ein Beispiel. Verwenden Sie hier die für Ihre Umgebung bereitgestellte BusinessGPT-API-URL.

4.2. Header setzen

In Postman (oder einem ähnlichen Tool):

  1. Wechseln Sie in Ihrem Request auf den Tab „Headers“.

  2. Stellen Sie sicher, dass folgende Header gesetzt sind:

  3. Authorization: Bearer <access_token>
    (In vielen Tools wird dies nach dem Tokenabruf automatisch gesetzt.)

  4. Content-Type: application/json

Postman

4.3. Beispiel-Body für einen Chat-Aufruf

Nachfolgend ein Beispiel für einen Request-Body (alle IDs und Texte sind Platzhalter):

{
  "model": "8a5b559d-92f8-48ad-980c-b300822930c9",
  "messages": [
    {
      "role": "user",
      "content": "Erklären Sie mir in einfachen Worten, wie der API-Zugriff auf BusinessGPT funktioniert."
    }
  ]
}

Postman

  • model: Die Modell-ID aus Ihrer BusinessGPT-Instanz (siehe Kapitel 5).
  • messages: Ein Array von Chat-Nachrichten, bestehend aus role (user, assistant, etc.) und content.

Klicken Sie auf „Send“.

Bei erfolgreichem Aufruf sollten Sie sehen:

  • Statuscode: 200 OK
  • Im Response-Body:
    • Eine vom Modell generierte Antwort
    • Ggf. weitere Metadaten (abhängig von der konkreten API-Implementierung)

Postman

5. Modell-IDs (Feld model) in BusinessGPT ermitteln

Damit BusinessGPT weiß, welches Modell Sie ansprechen möchten (z. B. GPT-4o, Document Chat, Internet-Suche), müssen Sie die entsprechende Modell-ID kennen.

5.1. Modell-ID im BusinessGPT-Frontend herausfinden

  1. Öffnen Sie die BusinessGPT-Weboberfläche in Ihrem Browser.
  2. Wählen Sie das gewünschte Modell oder einen Ihrer eigenen Assistenten aus.
  3. Schauen Sie sich die URL in der Adresszeile des Browsers an:
  4. Kopieren Sie diese ID und verwenden Sie sie im API-Request im Feld "model".

App-Registrierung

Assistenten-IDs

Eigene Assistenten, die Sie in BusinessGPT erstellen, erhalten ebenfalls eine eindeutige ID. Diese ID können Sie genauso wie die Standard-Modelle im Feld model verwenden.

5.2. Beispielhafte Modell-IDs (nur zur Illustration)

Die folgenden IDs dienen lediglich als Beispiele:

Zweck / Modell Beispielhafte Modell-ID
Document Chat 1226a08b-7fad-4c99-aeac-b695ea5b250b
GPT-4o 8a5b999d-92f8-48ag-980c-b300822930c9
GPT-4o mini 1691aea7-ed0b-46ce-9aef-dd729dbdbecc
GPT-o1 7406483d-1dde-49be-9bc8-6703h948590b
GPT-o3 (mini) be3ad08c-d906-4308-afbb-e348493e3458
DALL‑E dfcf580b-7ed1-47d5-843d-9ce818349e24
Internet-Suche 8b16032e-e39d-401c-b3bd-3366e73511d5

Hinweis

Diese IDs sind Beispiele. Verwenden Sie die Modell-IDs, die in Ihrer eigenen BusinessGPT-Instanz angezeigt werden.

6. Typische Fehler und Tipps zur Fehlersuche

6.1. Häufige Probleme bei der Token-Anforderung

  • 401 Unauthorized / 403 Forbidden
  • Scope ist falsch oder passt nicht zur App-Registrierung
  • Client ID oder Client Secret sind fehlerhaft

  • Admin-Consent wurde noch nicht erteilt

  • „invalid_grant“ oder „invalid_client“

  • Client Secret ist abgelaufen oder wurde falsch kopiert
  • Tenant-ID ist nicht korrekt

6.2. Häufige Probleme bei API-Aufrufen

  • 404 oder 400 (Bad Request)
  • Falsche oder nicht existente Modell-ID

  • Falsche oder unvollständige URL

  • Unerwartete Fehlermeldungen

  • Falsche Header (z. B. fehlendes Content-Type: application/json)
  • Fehler in der JSON-Struktur des Request-Bodys

6.3. Empfehlung für eine kurze Checkliste

Wenn etwas nicht funktioniert, prüfen Sie bitte zuerst:

  1. Ist die Tenant-ID korrekt?
  2. Haben Sie die richtige Client ID und das korrekte Client Secret verwendet?
  3. Ist der Scope korrekt konfiguriert?
  4. Ist die gewünschte Rolle (z. B. user oder admin) zugewiesen?
  5. Wurde der Admin-Consent bereits erteilt?
  6. Verwenden Sie die richtige BusinessGPT-API-URL und eine gültige Modell-ID?“