eStamp: Structure, use, and authentication for PDF signatures

Content

eStamp is a service provided by XiTrust for automatically signing and sealing documents via a REST API or a web client. This document describes basic concepts, deployment options, authentication methods, and a quick start guide for new integration teams.

What is eStamp?

eStamp is a service that automatically signs or seals PDF documents (and XML files). The process is always the same:

The calling system sends a document to the eStamp REST API.
eStamp signs or seals the document with the configured certificate.
The signed document is returned directly as a response.

eStamp is designed for organizations that need to sign many documents automatically and in compliance with legal requirements—without manual intervention. Typical areas of application include government agencies (notices, official signatures), insurance companies (policies, confirmations), and financial service providers (automatically generated contract documents).

Deployment options for eStamp

eStamp can be operated in two ways. The choice of option determines who is responsible for operation and updates.

Cloud option (recommended): eStamp is hosted by XiTrust as part of the MOXIS platform. Deployment is carried out by the XiTrust support team. No separate server is required.

On-premises: eStamp is installed and operated in the customer's own IT infrastructure. Installation and ongoing operation are the responsibility of the customer's team.

The following applies to both variants: Each eStamp instance receives its own customer-specific base URL (e. g. https://estamp.kunde.xitrust.cloud/estamp). This URL is specified during deployment and is a prerequisite for every API call.

[!NOTE] eStamp does not use a client model. Different configurations (e.g., different certificates or signature types) are mapped within an instance using signature handlers. A separate eStamp instance is recommended to ensure complete technical separation between organizational units.

eStamp Base URL

The eStamp Base URL is the customer-specific web address through which an eStamp instance can be accessed. All API calls use this URL as a basis.

Format:

CODE

https://estamp.<customername>.xitrust.cloud/estamp

Beispiel:

CODE

https://estamp.acc.xitrust.cloud/estamp

The base URL is specified during deployment and communicated by the XiTrust support team. Without the correct base URL, all API calls will fail with a 404 Not Found error.

[!WARNING] The eStamp base URL is customer-specific and individual. An incorrect or generic URL will result in 404 errors. If an eStamp service is unavailable, the base URL is the first thing to check.

Authentication and access protection

The eStamp REST API is secure. Please note: As of version 4.54, the licenseInfos GET call is executed without authentication.

However, without valid authentication, no API calls are accepted—neither signing operations nor session management.

eStamp supports two authentication methods:

OAuth 2.0 (recommended): Modern, token-based authentication with the grant type “Client Credentials.” A machine or system authenticates itself—not a human user. OAuth 2.0 is the recommended method for all new integrations.

Basic Authorization: Classic authentication with username and password as HTTP headers. Less recommended than OAuth 2.0.

[!NOTE] eStamp does not use RBAC, user roles, or different authorization levels. Every validly authenticated client can use all protected endpoints. The only exception are license information endpoints, which are accessible without protection.

OAuth 2.0 in eStamp: Configuration and Process

eStamp uses OAuth 2.0 with the grant type “Client Credentials.” This process is specifically designed for machine-to-machine communication.

Required OAuth 2.0 configuration values

The following five values are mandatory for OAuth 2.0 authentication against eStamp. All of them are defined and communicated by the XiTrust support team during deployment:

Value	Description
`client_id`	The “user name” of the application on the authentication server.
`client_secret`	The application's “password” – only the application and the authentication server know this value.
`issuer-uri`	The “home address” of the identity provider (e.g., Keycloak) identifies the token issuer.
`auth-server-url`	The specific URL of the authentication server to which token requests are sent.
`grant_type`	Always `client_credentials` for eStamp-integrations

Step 1: Request a bearer token

bash

CODE

# eStamp OAuth 2.0: Request bearer token
# Endpoint: POST /token on the configured authentication server
# Grant Type: client_credentials (machine-to-machine)

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>"

Successful Response (200 OK):

json

CODE

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

Step 2: Use the bearer token for every API call

The bearer token is sent for every eStamp API call in the Authorization-Header:

CODE

Authorization: Bearer <access_token>

[!WARNING] The eStamp Bearer Token has a limited validity period (expires_in). After expiration, the eStamp API returns error 451 Unavailable for Legal Reasons (JWT token is expired). Implement automatic token renewal in your integration before the validity period expires.

[!IMPORTANT] Bearer tokens should be treated like passwords. Access data (client_id, client_secret, Bearer Token) must never be stored in source code, plain text configuration files, or version control systems. Recommended storage: Secret Manager (e.g., HashiCorp Vault, Keycloak, AWS Secrets Manager).

Testing the eStamp API with Swagger

Swagger is the interactive API documentation platform that is automatically generated based on eStamp's OpenAPI specification. Swagger allows you to test all eStamp endpoints directly in your browser without having to write your own code.

Swagger URL: Swagger can be accessed via the respective eStamp instance. The exact URL will be communicated by the XiTrust support team during deployment.

Using Swagger with OAuth 2.0

Open the Swagger UI of the eStamp instance in your browser.
Click on the [Authorize] button in the top right corner.
Enter your client_id and client_secret. Swagger automatically requests a bearer token and sets it for all subsequent test requests.
Execute any eStamp endpoints directly in the browser.

[!NOTE] Swagger is suitable for initial testing and exploration of the eStamp REST API. For production integrations, direct API use via HTTP clients (curl, Postman, programmatic clients) is recommended.

Quick start: Seal your first PDF with eStamp

This quick start guide shows you the minimum steps required to seal a PDF using the eStamp REST API. Requirements: valid eStamp base URL and valid OAuth 2.0 access data.

Step 1: Query available signature handlers

Before the first sealing call, the available parameterId values of the eStamp instance must be queried. The parameterId is a mandatory field for every seal call and controls which signature handler and which certificate is used.

bash

CODE

# eStamp: Query available signature handlers
# Endpoint: GET /signApi/parameterInfos
# Authentifizierung: Bearer Token required

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

Successful response (200 OK):

json

CODE

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

If this call is successful, the base URL, authentication, and availability of the eStamp service are correct.

Common mistake in this step:

CODE

404 Not Found – "Cannot find handler for parameter"

Causes: incorrect base URL, incorrect path, incorrect handler ID name. Check the base URL, token, and endpoint path carefully for spelling and capitalization.

Step 2: Seal PDF (synchronous workflow)

bash

CODE

# 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://estamp.acc.xitrust.cloud/estamp/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

Result: The signed PDF is returned as a binary file and saved under signiert.pdf.

[!NOTE] documentToSign and file are synonymous field names and have the same meaning. Both variants are accepted by the eStamp REST API. The different names arose due to historical customer requirements.

FAQ: Authentication and basic concepts

What specific base URL do customers receive?

Each customer receives their own customer-specific base URL for their eStamp instance, for example https://estamp.kunde.xitrust.cloud/estamp. The base URL is determined and communicated by the XiTrust support team during deployment. Without the correct base URL, no eStamp API calls are possible.

Does eStamp have a client model?

No, eStamp does not have a client model. Different configurations (e.g., different certificates, signature types, or signature visualizations) are mapped via signature handlers within an eStamp instance. A separate eStamp instance is recommended for complete technical separation between organizational units.

Is there API versioning?

No, eStamp does not use URL-based API versioning (such as /api/v1/). Instead, XiTrust guarantees that no breaking changes will be made. Existing integrations will continue to function after updates. The last 3 eStamp versions are actively supported.

Are there roles or permission levels?

No, eStamp does not use RBAC (Role-Based Access Control).

There are no user roles or different permission levels. Every validly authenticated client can use all protected eStamp endpoints.

Which TLS version is required by eStamp?

eStamp requires at least TLS 1.2. The standard is TLS 1.3. Older TLS versions are not accepted.

How do I contact eStamp support?

If you have any questions or problems, please contact the XiTrust support team:

Service Desk Ticket: via the XiTrust Service Desk Portal
Email: servicedesk@xitrust.com

The following information is helpful for support requests regarding API errors:

Timestamp of the request,
endpoint used,
sessionId (if available), and
complete HTTP status code