eStamp: Aufbau, Nutzung und Authentifizierung für PDF-Signaturen

Inhalt

eStamp ist ein Service von XiTrust zum automatischen Signieren und Siegeln von Dokumenten über eine REST-API oder einen Webclient. Dieses Dokument beschreibt Grundkonzepte, Deployment-Varianten, Authentifizierungsmethoden und einen Quickstart für neue Integrations-Teams.

Was ist eStamp?

eStamp ist ein Dienst, der PDF-Dokumente (und XML-Dateien) automatisiert signiert oder versiegelt. Der Ablauf ist dabei immer gleich:

Das aufrufende System sendet ein Dokument an die eStamp REST-API.
eStamp signiert oder versiegelt das Dokument mit dem konfigurierten Zertifikat.
Das signierte Dokument wird direkt als Antwort zurückgegeben.

eStamp ist für Organisationen konzipiert, die viele Dokumente automatisiert und rechtskonform signieren müssen – ohne manuelle Eingriffe. Typische Anwendungsbereiche sind Behörden (Bescheide, Amtssignaturen), Versicherungen (Polizzen, Bestätigungen) und Finanzdienstleister (automatisch generierte Vertragsdokumente).

Deployment-Varianten von eStamp

eStamp kann auf zwei Arten betrieben werden. Die Wahl der Variante beeinflusst, wer für Betrieb und Updates zuständig ist.

Cloud-Variante (empfohlen): eStamp wird durch XiTrust als Teil der MOXIS-Plattform gehostet. Das Deployment wird durch das XiTrust Support Team durchgeführt. Es wird kein eigener Server benötigt.

On-Premises: eStamp wird in der eigenen IT-Infrastruktur des Kunden installiert und betrieben. Installation und laufender Betrieb liegen beim Kunden-Team.

In beiden Varianten gilt: Jede eStamp-Instanz erhält eine eigene, kundenspezifische Base URL (z. B. https://pbss.kunde.xitrust.cloud/pbss). Diese URL wird beim Deployment festgelegt und ist Voraussetzung für jeden API-Aufruf.

[!NOTE] eStamp kennt kein Mandantenmodell. Unterschiedliche Konfigurationen (z. B. verschiedene Zertifikate oder Signaturtypen) werden über Signaturhandler innerhalb einer Instanz abgebildet. Für eine vollständige technische Trennung zwischen Organisationseinheiten wird eine separate eStamp-Instanz empfohlen.

eStamp Base URL

Die eStamp Base URL ist die kundenspezifische Webadresse, über die eine eStamp-Instanz erreichbar ist. Alle API-Aufrufe verwenden diese URL als Basis.

Format:

https://pbss.<kundenname>.xitrust.cloud/pbss

Beispiel:

https://pbss.acc.xitrust.cloud/pbss

Die Base URL wird beim Deployment festgelegt und vom XiTrust Support Team kommuniziert. Ohne korrekte Base URL schlagen alle API-Aufrufe mit einem 404 Not Found-Fehler fehl.

[!WARNING] Die eStamp Base URL ist kundenspezifisch und individuell. Eine falsche oder allgemeine URL führt zu 404-Fehlern. Wenn ein eStamp-Service nicht erreichbar ist, ist die Base URL der erste zu prüfende Punkt.

Authentifizierung und Zugriffsschutz

Die eStamp REST-API ist an sich abgesichtert. Bitte beachten Sie: ab Version 4.54 wird der licenceInfos GET Call ohne Authentifizierung ausgeführt.

Ohne gültige Authentifizierung werden jedoch keine API-Aufrufe akzeptiert – weder Signieroperationen noch Session-Management.

eStamp unterstützt zwei Authentifizierungsmethoden:

OAuth 2.0 (empfohlen): Moderne, token-basierte Authentifizierung mit dem Grant Type „Client Credentials". Eine Maschine bzw. ein System authentifiziert sich – kein menschlicher Benutzer. OAuth 2.0 ist die empfohlene Methode für alle neuen Integrationen.

Basic Authorization: Klassische Authentifizierung mit Benutzername und Passwort als HTTP-Header. Weniger empfohlen als OAuth 2.0.

[!NOTE] eStamp verwendet keine RBAC, keine User-Rollen und keine unterschiedlichen Berechtigungsstufen. Jeder gültig authentifizierte Client kann alle geschützten Endpoints verwenden. Die einzige Ausnahme sind Lizenzinformations-Endpoints, die ungeschützt erreichbar sind.

OAuth 2.0 in eStamp: Konfiguration und Ablauf

eStamp verwendet OAuth 2.0 mit dem Grant Type „Client Credentials". Dieser Ablauf ist speziell für Maschine-zu-Maschine-Kommunikation ausgelegt.

Benötigte OAuth-2.0-Konfigurationswerte

Folgende fünf Werte sind für die OAuth-2.0-Authentifizierung gegen eStamp verpflichtend. Alle werden beim Deployment vom XiTrust Support Team festgelegt und kommuniziert:

Wert	Beschreibung
`client_id`	Der „Benutzername" der Anwendung beim Authentifizierungsserver
`client_secret`	Das „Passwort" der Anwendung – nur Anwendung und Auth-Server kennen diesen Wert
`issuer-uri`	Die „Heimatadresse" des Identity Providers (z. B. Keycloak), identifiziert den Token-Aussteller
`auth-server-url`	Die konkrete URL des Authentifizierungsservers, an die Token-Anfragen gesendet werden
`grant_type`	Immer `client_credentials` für eStamp-Integrationen

Schritt 1: Bearer Token anfordern

bash

# eStamp OAuth 2.0: Bearer Token anfordern
# Endpoint: POST /token am konfigurierten Auth-Server
# Grant Type: client_credentials (Maschine-zu-Maschine)

curl -X POST "https://<auth-server-url>/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>"

Erfolgreiche Antwort (200 OK):

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Schritt 2: Bearer Token bei jedem API-Aufruf verwenden

Der Bearer Token wird bei jedem eStamp-API-Aufruf im Authorization-Header mitgesendet:

Authorization: Bearer <access_token>

[!WARNING] Der eStamp Bearer Token hat eine begrenzte Gültigkeitsdauer (expires_in). Nach Ablauf liefert die eStamp API den Fehler 451 Unavailable for Legal Reasons (JWT token is expired). Implementieren Sie in Ihrer Integration eine automatische Token-Erneuerung vor Ablauf der Gültigkeitsdauer.

[!IMPORTANT] Bearer Tokens sind wie Passwörter zu behandeln. Zugangsdaten (client_id, client_secret, Bearer Token) dürfen niemals im Quellcode, in Klartext-Konfigurationsdateien oder in Versionskontrollsystemen gespeichert werden. Empfohlene Ablage: Secret Manager (z. B. HashiCorp Vault, Keycloak, AWS Secrets Manager).

eStamp API testen mit Swagger

Swagger ist die interaktive API-Dokumentationsplattform, die auf Basis der OpenAPI-Spezifikation von eStamp automatisch generiert wird. Swagger ermöglicht das direkte Testen aller eStamp-Endpunkte im Browser, ohne eigenen Code schreiben zu müssen.

Swagger-URL: Swagger ist über die jeweilige eStamp-Instanz erreichbar. Die genaue URL wird beim Deployment vom XiTrust Support Team kommuniziert.

Swagger mit OAuth 2.0 verwenden

Öffnen Sie die Swagger-UI der eStamp-Instanz im Browser.
Klicken Sie auf den [Authorize]-Button oben rechts.
Geben Sie client_id und client_secret ein. Swagger fordert automatisch einen Bearer Token an und setzt ihn für alle nachfolgenden Test-Requests.
Führen Sie beliebige eStamp-Endpunkte direkt im Browser aus.

[!NOTE] Swagger eignet sich für initiale Tests und Exploration der eStamp REST-API. Für Produktions-Integrationen wird die direkte API-Nutzung über HTTP-Clients (curl, Postman, programmatische Clients) empfohlen.

Quickstart: Erstes PDF mit eStamp versiegeln

Dieser Quickstart zeigt den minimalen Ablauf, um ein PDF über die eStamp REST-API zu versiegeln. Voraussetzungen: gültige eStamp Base URL und gültige OAuth-2.0-Zugangsdaten.

Schritt 1: Verfügbare Signaturhandler abfragen

Vor dem ersten Versiegelungsaufruf müssen die verfügbaren parameterId-Werte der eStamp-Instanz abgefragt werden. Die parameterId ist ein Pflichtfeld bei jedem Seal-Aufruf und steuert, welcher Signaturhandler und welches Zertifikat verwendet wird.

bash

# eStamp: Verfügbare Signaturhandler abfragen
# Endpoint: GET /signApi/parameterInfos
# Authentifizierung: Bearer Token erforderlich

curl -X GET "https://pbss.acc.xitrust.cloud/pbss/signApi/parameterInfos" \
  -H "Authorization: Bearer <token>"

Erfolgreiche Antwort (200 OK):

json

[
  {
    "parameterId": "amtssignatur",
    "displayName": "Amtssignatur",
    "maxNumberOfDocuments": 100,
    "signatureHandlerType": "SOFTWARE_KEY"
  }
]

Wenn dieser Aufruf erfolgreich ist, sind Base URL, Authentifizierung und Erreichbarkeit des eStamp-Services korrekt.

Typischer Fehler bei diesem Schritt:

404 Not Found – "Cannot find handler for parameter"

Ursachen: falsche Base URL, falscher Pfad, falsche Bezeichnung der Handler-ID. Prüfen Sie Base URL, Token und Endpoint-Pfad exakt auf Schreibweise und Groß-/Kleinschreibung.

Schritt 2: PDF versiegeln (synchroner Workflow)

bash

# eStamp: PDF versiegeln (synchroner Workflow ohne Visualisierung)
# Endpoint: POST /signApi/sealSingle
# Authentifizierung: Bearer Token erforderlich
# Rückgabe: signiertes PDF als Binary

curl -X POST "https://pbss.acc.xitrust.cloud/pbss/signApi/sealSingle" \
  -H "Authorization: Bearer <token>" \
  -H "accept: application/pdf" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=amtssignatur" \
  -F "documentToSign=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Ergebnis: Das signierte PDF wird als Binary zurückgegeben und unter signiert.pdf gespeichert.

[!NOTE] documentToSign und file sind synonyme Feldbezeichnungen und haben dieselbe Bedeutung. Beide Varianten werden von der eStamp REST-API akzeptiert. Die unterschiedlichen Namen entstanden durch historische Kundenanforderungen.

FAQ: Authentifizierung und Grundkonzepte

Welche Base URL bekommen Kunden konkret?

Jeder Kunde erhält eine eigene, kundenspezifische Base URL für seine eStamp-Instanz, zum Beispiel https://pbss.kunde.xitrust.cloud/pbss. Die Base URL wird beim Deployment vom XiTrust Support Team festgelegt und kommuniziert. Ohne korrekte Base URL sind keine eStamp-API-Aufrufe möglich.

Hat eStamp ein Mandantenmodell?

Nein, eStamp kennt kein Mandantenmodell. Unterschiedliche Konfigurationen (z. B. verschiedene Zertifikate, Signaturtypen oder Signatur-Visualisierungen) werden über Signaturhandler innerhalb einer eStamp-Instanz abgebildet. Für eine vollständige technische Trennung zwischen Organisationseinheiten wird eine separate eStamp-Instanz empfohlen.

Gibt es eine API-Versionierung?

Nein, eStamp verwendet keine URL-basierte API-Versionierung (wie /api/v1/). Stattdessen garantiert XiTrust, dass keine Breaking Changes durchgeführt werden. Bestehende Integrationen bleiben nach Updates weiterhin funktionsfähig. Die letzten 3 eStamp-Versionen werden aktiv supportet.

Gibt es Rollen oder Berechtigungsstufen?

Nein, eStamp verwendet kein RBAC (Role-Based Access Control). Es gibt keine User-Rollen oder unterschiedliche Berechtigungsstufen. Jeder gültig authentifizierte Client kann alle geschützten eStamp-Endpunkte verwenden.

Welche TLS-Version wird von eStamp erwartet?

eStamp erfordert mindestens TLS 1.2. Standard ist TLS 1.3. Ältere TLS-Versionen werden nicht akzeptiert.

Wie erreiche ich den eStamp Support?

Bei Fragen oder Problemen wenden Sie sich an das XiTrust Support Team:

Service Desk Ticket: über das XiTrust Service Desk Portal
E-Mail: servicedesk@xitrust.com

Für Supportanfragen zu API-Fehlern sind folgende Informationen hilfreich:

Timestamp der Anfrage,
verwendeter Endpoint,
sessionId (falls vorhanden) und
vollständiger HTTP-Statuscode