Zum Hauptinhalt springen
Alles, was du im Portal tust, läuft über die REST-API von msg.Hello. Willst du Abläufe automatisieren, etwa Agenten zwischen Umgebungen übertragen oder ausgehende Anrufe aus deinem System auslösen, greifst du mit einem eigenen OIDC-Client direkt auf diese API zu.
Die Adressen deiner Umgebung, also die API-Basis-URL und die Issuer-URL des Identity-Dienstes, erhältst du von msg. In den Beispielen stehen dafür <API-Host> und <IAM-Host>.

​
Der Weg zum API-Aufruf

1

Client anlegen

Öffne in der Benutzer- und Rechteverwaltung deines Mandanten den Bereich Clients und wähle Neuen Client hinzufügen. Vergib eine Beschreibung und setze den Haken bei Vertraulich. Nach dem Anlegen findest du Client-ID und Client Secret im Tab Schlüssel.
2

Rollen zuweisen

Öffne im Client den Tab Rollen und wähle Rollen zuweisen. Du kannst dem Client die Standard-Rollen deines Mandanten und deine eigenen Rollen geben. Der Client darf genau das, was diese Rollen erlauben.
3

Token abrufen

Dein System tauscht Client-ID und Secret am Token-Endpunkt gegen ein kurzlebiges Access-Token (OAuth Client Credentials).
4

API aufrufen

Sende das Token bei jedem Aufruf im Header Authorization: Bearer <Token> mit.
Behandle das Client Secret wie ein Passwort. Gib dem Client nur die Rollen, die er für seine Aufgabe braucht, und lege für unterschiedliche Systeme getrennte Clients an.

​
Token abrufen

Den Token-Endpunkt findest du über die OpenID-Discovery unter https://<IAM-Host>/.well-known/openid-configuration. Fordere den Scope tenant_permission an, damit die Berechtigungen aus den Rollen des Clients im Token landen.
Die Antwort enthält das access_token und seine Laufzeit in expires_in. Hole rechtzeitig vor Ablauf ein neues Token. Das Token ist an deinen Mandanten gebunden und funktioniert nur für dessen Daten.

​
API aufrufen

Alle mandantenbezogenen Endpunkte beginnen mit /tenants/{tid}, wobei {tid} die ID deines Mandanten ist. Mandanten-ID und Agenten-ID siehst du im Portal in der Adresszeile des Browsers, etwa in /tenants/<tid>/agents/<botId>. Ein Beispiel ist der Export eines Agenten.

​
Berechtigungen

Jeder Endpunkt prüft, ob das Token die passende Berechtigung trägt. Für die neueren Automatisierungs-Endpunkte sind das die folgenden. Welche Rolle welche Berechtigung enthält, siehst du in der Rechteverwaltung. Fehlt eine Berechtigung, antwortet die API mit 403. Weise dem Client dann eine passende Rolle zu oder lege eine eigene Rolle mit genau diesen Rechten an.

​
Clients mit Benutzer-Anmeldung

Soll sich statt eines Systems eine Person anmelden, etwa in einem eigenen Werkzeug, legst du den Client ohne den Haken bei Vertraulich an und trägst die Redirect URIs deiner Anwendung ein. Das Token trägt dann die Rechte der angemeldeten Person. Solche öffentlichen Clients müssen den Authorization-Code-Flow mit PKCE und der Methode S256 verwenden. Anfragen ohne Code-Challenge oder mit einer anderen Methode lehnt der Identity-Dienst ab. Wurde bei der Anmeldung eine Code-Challenge gesendet, ist beim Token-Abruf der passende code_verifier Pflicht.

​
Tokens prüfen

Ein Dienst, der Tokens von msg.Hello entgegennimmt, kann sie am Endpunkt https://<IAM-Host>/protocol/oidc/introspect prüfen (Token Introspection nach RFC 7662). Der Dienst meldet sich dort mit Client-ID und Secret eines vertraulichen Clients per HTTP Basic an. Die Antwort sagt, ob das Token noch gültig ist, und enthält seine Angaben wie Client, Scope und Ablaufzeit.