Integration
API-Token
Verwalten Sie API-Tokens für die Integration externer Systeme
Die API-Token-Verwaltung ermöglichen eine sichere und automatisierte Integration externer Systeme, indem sie den Zugriff auf die Funktionen des Output-Management-Systems authentifizieren und autorisieren.
Bei einem klassischen API-Token wird der Tokenwert automatisch erzeugt und in der Detailansicht angezeigt. Das Geheimnis eines OAuth-Zugangs wird nur beim Anlegen oder Wechsel angezeigt. Speichern Sie es deshalb sofort sicher im Fachsystem.
Erstellen Sie hier API-Tokens, deren Wert sie danach in ihren Systemen verwenden können.
Archivzugänge und OAuth 2.0
Für die Archiv-API können Administratoren beim Anlegen zwischen einem API-Token und OAuth 2.0 Client Credentials wählen. Beide Zugänge können einem Mandanten oder einem festen Umgebungs-Mandanten zugeordnet werden. Die Rechteprofile Nur ablegen, Nur lesen und Verwalten begrenzen Archivoperationen. Schutz und Löschung müssen ausdrücklich als einzelne Rechte gewählt werden. Ein Ablaufdatum kann den Zugang zeitlich begrenzen.
Bei OAuth erhalten Sie eine Client-ID und ein Geheimnis. Das Geheimnis wird nur direkt nach dem Anlegen oder Wechsel angezeigt. Fordern Sie mit grant_type=client_credentials an /api/archive/oauth/token ein zehn Minuten gültiges Zugriffstoken an und senden Sie es als Authorization: Bearer ACCESS_TOKEN. Der angeforderte scope darf nur bereits vergebene Archiv-Rechte enthalten. Bestehende API-Tokens behalten ihre bisherigen Rechte; sie werden weiterhin als X-AUTH-TOKEN gesendet.
Beim Rotieren eines Tokens oder OAuth-Geheimnisses gilt der neue Wert sofort. Der bisherige Wert kann noch für eine wählbare Übergangszeit von einer Minute bis zu sieben Tagen verwendet werden; voreingestellt sind 24 Stunden. Die Detailansicht zeigt, wann der alte Wert abläuft und wann beide Werte zuletzt verwendet wurden (auf etwa eine Minute genau). Prüfen Sie insbesondere selten laufende Anbindungen, bevor Sie den alten Wert vorzeitig sperren. Bei Verdacht auf ein offengelegtes Geheimnis verwenden Sie die Notfallrotation: Sie sperrt alle bisherigen Werte sofort. Änderungen oder Entzug von Rechten beenden auch laufende Archiv-Suchsitzungen. Ein abgelaufener Zugang liefert HTTP 401.
Umstellung für Archivintegrationen: Der Parameter auth-token in URL oder Formular wird an /api/archive nicht mehr angenommen. Übernehmen Sie denselben Tokenwert in den Header X-AUTH-TOKEN; für OAuth verwenden Sie Authorization: Bearer. Prüfen Sie insbesondere gespeicherte URLs und Skripte auf den alten Parameter.
API-Token-Liste
ID, Identifier, Aktiv ab, Aktiv, Beschreibung
| ID | Identifier | Gruppen-Identifier | Aktiv ab | Aktiv | Beschreibung |
|---|---|---|---|---|---|
| identifier_name | Null | Aktiv |
ID
Eindeutige Nummer zur internen Identifikation des API-Tokens.
Identifier
Eindeutiger Name des API-Tokens für Rendering und API-Aufrufe.
Eindeutiger Name für eine optionale Gruppierung von verwandten API-Tokenn. Elemente einer Gruppe werden gemeinsam verarbeitet und optionale Validatoren können dabei einzelne Elemente aktivieren oder ignorieren.
Aktiv ab
Startdatum eines API-Tokens. API-Tokens werden erst ab diesem Datum beim Rendern beachtet.
Aktiv
Schnellübersicht, ob das API-Token derzeit freigegeben ist. Deaktivierte Elemente behalten ihre Historie, werden aber nicht mehr automatisch verwendet.
Beschreibung
Beschreibung zur schnellen Einordnung im Backend. Unterstützt frei formulierte, redaktionelle Hinweise zur Funktion oder zum Einsatzzweck des/r API-Tokens.
Verwenden Sie sprechende Identifier wie retool-backoffice-ui oder sns-reporting-gateway, damit klar bleibt, welches System auf das Token zugreift. „Aktiv ab“ eignet sich, um Tokens bereits vor Produktivstart anzulegen und erst später freizuschalten.
Mandant
Bei aktiviertem Modul „Umgebungs-Mandanten“ zeigt die Spalte die Berechtigung: Hauptmandant, ein fest zugeordneter Umgebungs-Mandant oder ein zentrales Token mit seiner Liste erlaubter Umgebungs-Mandanten.
Erstellt am, Aktualisiert am
| Validatoren | Pausiert | Erstellt am | Aktualisiert am |
|---|---|---|---|
| Null | NO | ||
| missing_street | YES |
Zugewiesene Validierungsregeln für das API-Token. Prüfen Ihre Bedingungen vor der Verarbeitung und aktivieren/deaktivieren das Rendering entsprechend.
Temporäre Deaktivierung des API-Tokens. Pausierte Elemente werden nicht verarbeitet.
Erstellt am
Zeitstempel der API-Token-Erstellung.
Aktualisiert am
Zeitstempel der letzten Änderung. Zeigt wann API-Token-Konfiguration zuletzt bearbeitet wurde.
Kontext-Aktionen
Aktions-Dropdown
Aktions-Dropdown
Klicken Sie auf das Drei-Punkte-Menü am Ende jeder Zeile für Aktionen mit dem jeweiligen API-Token.
Testen
Öffnet eine API-Token-Testumgebung zum lokalen Rendern mit bearbeitbaren Validatoren und JSON-Testdaten.
API-Token herunterladen
Lädt die Quell-Datei des API-Token auf Ihren Computer herunter.
Anzeigen
Öffnet eine reine Detailansicht der kompletten Meta-Informationen und Einstellungen des API-Token.
Ändern
Öffnet das Bearbeitungsformular für alle Einstellungen und den Upload einer neuen API-Token-Version.
Löschen
Entfernt das API-Token dauerhaft aus dem System. Diese Aktion kann nicht rückgängig gemacht werden.
Der aktuelle Token-Wert wird in der Detailansicht angezeigt und kann kopiert oder rotiert werden. Der alte Wert wird nach der Rotation nicht erneut angezeigt. OAuth-Geheimnisse werden nur direkt nach dem Anlegen oder Rotieren angezeigt. Deaktivieren Sie nicht mehr benötigte Tokens.
Filter
- Die Suche findet Identifier und Beschreibungen.
- Der Aktiv-Filter zeigt aktive oder inaktive Tokens.
- Zurücksetzen entfernt Suche, Aktiv-Filter und Sortierung.
Spalten konfigurieren
Passen Sie die Anzeige der API-Token-Liste für bessere Übersichtlichkeit an. Spalten können per Drag-and-Drop neu angeordnet und über Checkboxen ein-/ausgeblendet werden.
Für mich anwenden : Spalten-Konfiguration wird nur für Ihren Account gespeichert und beeinflusst andere Benutzer nicht.
Als Standard anwenden : Konfiguration wird für alle Benutzer der Instanz übernommen und als neue Standard-Ansicht gesetzt.
Die Spaltenkonfiguration wirkt benutzerbezogen: „Für mich anwenden“ speichert die Auswahl lokal, „Als Standard anwenden“ setzt die Ansicht für alle Teammitglieder, die denselben Mandanten verwalten.
API-Token erstellen
Aktions-Buttons zum Speichern und Verwalten der API-Token-Konfiguration.
Verwenden Sie "Erstellen und weiteres Element hinzufügen" für effizientes Batch-Erstellen mehrerer Elemente.
Der eigentliche Token-Wert wird nach dem Speichern vom System generiert und dann in der Detailansicht angezeigt. Das Formular erfasst Identifier, Beschreibung, Aktivierungszeitpunkt und bei aktiviertem Modul die Mandanten-Berechtigung.
Formularfelder
Identifier
Eindeutige Kennung für dieses/r API-Token zur programmatischen Verwendung, Einbindung in Vorlagen, Lookups und API-Zugriff.
Identifiers sollten 'snake_case' sein, also klein geschrieben und Unterstriche verwenden, z.B. 'kunde_name' oder 'rechnung_nummer'.
Aktiv ab und Aktiv
Startdatum des API-Tokens. API-Tokene werden erst ab diesem Datum beim Rendern beachtet.
Die Aktiv-Checkbox ermöglicht eine sofortige De-/Aktivierung unabhängig vom Datum.
Vor-Terminierung: Mit diesem Feld können API-Tokene vor-terminiert werden. Setzen Sie ein zukünftiges Datum, um das Element automatisch ab diesem Zeitpunkt zu aktivieren.
Mehrere Elemente mit gleichem Identifier: unterschiedliches 'Aktiv ab' staffelt die Version; bei einer Anfrage gilt das aktive Element mit dem spätesten Aktiv ab (nicht Erstell- oder Änderungsdatum).
Beschreibung
Interne Beschreibung eines/r API-Token für Identifikation und bessere Übersicht bzw. Dokumentation. Diese Beschreibung wird im Output.Rocks-Backend verwendet und nicht im Output angezeigt.
Beschreibungen sollten kurz und prägnant sein, um Übersichtlichkeit zu gewährleisten. Längere Erklärungen sollten im Feld 'Kommentar' platziert werden.
Mandant
Als Integrator oder Admin des Hauptmandanten können Sie bei aktiviertem Modul zwischen zwei Token-Typen wählen:
- Fest zugeordnet: Wählen Sie optional einen Umgebungs-Mandanten. Ohne Auswahl gehört das Token zum Hauptmandanten. Der Kontext gilt für alle Anfragen mit diesem Token, einschließlich
POST /api/renderings, und bleibt nach dem Erstellen fest. - Zentral: Wählen Sie mindestens einen erlaubten Umgebungs-Mandanten mit eindeutiger externer ID. Bei jeder API-Anfrage bestimmt der Header
X-SUB-CLIENTden Kontext. Der Header-Wert ist die externe ID (externalId, beispielsweiseb2b) des ausgewählten Umgebungs-Mandanten, nicht seine numerische ID oder Beschreibung. Ein zentrales Token hat keinen Standardkontext und keinen Zugriff auf den Hauptmandanten.
Die Auswahl für zentrale Tokens zeigt die Anzahl der gewählten Mandanten und lässt sich nach numerischer ID, Name oder externer ID durchsuchen. Sie können mehrere Mandanten nacheinander suchen und auswählen; bereits gewählte Mandanten bleiben beim Ändern der Suche erhalten. Mandanten ohne eindeutige gültige externe ID können nicht neu ausgewählt werden. Wenn die Mandantenliste nicht geladen werden kann, laden Sie die Seite neu, bevor Sie die Erlaubnisliste ändern.
Beispiel für einen Rendering-Aufruf mit einem zentralen Token und einem ausdrücklich erlaubten Umgebungs-Mandanten:
curl -X POST 'https://app.output.rocks/api/renderings' \
-H 'Content-Type: application/json' \
-H 'X-AUTH-TOKEN: beispiel-token-nur-fuer-die-dokumentation' \
-H 'X-SUB-CLIENT: b2b' \
-d '{"template":"beispiel_vorlage","format":"pdf","data":{}}'Fehlt X-SUB-CLIENT, ist die externe ID unbekannt oder steht der Umgebungs-Mandant nicht in der Erlaubnisliste, wird die Anfrage abgewiesen. Es gibt keinen Rückfall auf den Hauptmandanten. Die Erlaubnisliste lässt sich beim Bearbeiten eines zentralen Tokens erweitern oder einschränken; sie muss mindestens einen Mandanten enthalten. Um alle Berechtigungen sofort zu entziehen, deaktivieren Sie das Token.
Fest zugeordnete Tokens funktionieren ohne X-SUB-CLIENT wie bisher. Bei einem Token für einen Umgebungs-Mandanten darf der Header optional dessen eigene externe ID enthalten; ein abweichender Wert wird abgewiesen. Ein fest dem Hauptmandanten zugeordnetes Token akzeptiert keine Mandantenauswahl per Header. Verwenden Sie dafür ein zentrales Token.
Der Token-Typ bleibt nach dem Erstellen fest. Für einen anderen festen Kontext erstellen Sie ein neues Token und deaktivieren das bisherige nach der Umstellung. Benutzer eines Umgebungs-Mandanten können Tokens nur in ihrem eigenen Kontext erstellen und verwalten. Die Token-Konfiguration ändert weder Benutzeranmeldungen noch vorhandene Kundenzugangsdaten automatisch.
Bei COMS-Integrationen gelten zusätzlich die eigenen Mandanten- und Berechtigungsprüfungen von COMS. Ein erlaubter Umgebungs-Mandant im Token ersetzt diese Prüfung nicht.
Verwandte Backend-Bereiche
- Zugangsdaten: Hinterlegen Sie weitere Authentifizierungs-Informationen für externe Systeme und binden Sie sie an Token-gestützte Prozesse.
- E-Mail-Server: Verwalten Sie SMTP-Konfigurationen, die nach erfolgreicher Token-Authentifizierung Trigger für automatisierte Zustellungen verwenden.
- Webhooks: Definieren Sie Antwort-Endpunkte, die nach authentifizierten Requests mit API-Token aufgerufen werden.
Relevante Use Cases
- API-Integration mit Output.Rocks: Vollständige Einführung in die API-Nutzung, Authentifizierung und Powercloud-Integration.
- Benutzerdefinierte Zugangsdaten: Zeigt, wie Token-basierte Konfigurationen mit E-Mail- und Dokumenten-Prozessen zusammenspielen.
- Mandanten-Management: Erklärt die Sichtbarkeit von Mandanten-bezogenen Elementen.
API-Referenzen & Funktionen
- API Endpoint: POST /renderings: Dokumentiert den Standard-API-Aufruf, der mit API-Tokens authentifiziert wird.
- API Reference: Enthält die vollständige Referenz aller verfügbaren Endpunkte, Modelle und Request-/Response-Schemata.