eStamp Glossary: Terms and concepts related to document signing

Content

This glossary defines all technical terms used in the eStamp documentation. It serves as an authoritative terminology reference for all other eStamp documents. Terms are grouped by topic and are self-explanatory - each entry contains product context, definition, and cross-references.

Target audience: Developers and administrators who are new to working with the eStamp REST API. Please direct support requests to the XiTrust support team at servicedesk@xitrust.com.

A: Architecture & Operation

This section explains the basic architecture and operating concepts of eStamp.

eStamp (product)

eStamp is a XiTrust service for automatically signing and sealing documents via a REST API or a web client. Documents are sent to the eStamp API as PDF files, signed or sealed, and returned as signed PDF files. Typical areas of application are public authorities (notices), insurance companies (policies), and businesses (automated document processes).

Synonyms in the system: eStamp is also referred to internally as the “Seal Service.” In the API, the base path is /signApi/....

→ See: [eStamp structure, use, and authentication for PDF signatures: What is eStamp?]

Base URL (eStamp instance address)

The eStamp base URL is the customer-specific web address through which an eStamp instance can be accessed. It is defined during deployment and is a prerequisite for every API call.

Format:

https://estamp.<customer name>.xitrust.cloud/estamp

Example:

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

[!WARNING] The base URL is individual for each customer. Without the correct base URL, all API calls will fail. If the service is not accessible, the base URL is the first checkpoint.

→ See: [eStamp structure, use, and authentication for PDF signatures: eStamp base URL]

eStamp instance

An eStamp instance is a stand-alone deployment of eStamp, either as a cloud variant (hosted by XiTrust) or as an on-premises installation (operated in the customer's infrastructure). Each instance has its own base URL and configuration.

Deployment variants:

Variant

Operation by

Server required

Cloud XiTrust Support Team No

On-premises Customer itself Yes

[!NOTE] For complete technical separation between organizational units (e.g., corporate structures), a separate eStamp instance is recommended. Note: Technical separation = separate instance.

Client model (eStamp)

eStamp does not use a client model. Unlike other systems, there are no separate clients within an eStamp instance. Instead, different configurations (e.g., different certificates, signature types, visualizations) are mapped within an instance using signature handlers.

Signature handler (eStamp)

An eStamp signature handler is a software component that controls the technical process of a signature operation. It determines which certificate is used and which seal behavior applies. A signature handler is selected via the parameterId in each seal call.

Query available handlers:

# eStamp API: Retrieve all configured signature handlers

GET /signApi/parameterInfos

Authorization: Bearer <token>

Example response:

[

{

“parameterId”: “software”,

“displayName”: “software”,

“maxNumberOfDocuments”: 100,

‘signatureHandlerType’: “SOFTWARE_KEY”

}

]

→ See: [eStamp API Reference and Endpoint Catalog: GET /signApi/parameterInfos]

B: Authentication & Security

This section explains all authentication concepts of the eStamp REST API. Without valid authentication, the eStamp API returns HTTP 401 and denies all signature and seal operations.

Basic Authorization (eStamp)

Basic Authorization is a simple authentication method for the eStamp API, in which classic access data (user name + password) is transferred as a Base64-encoded HTTP header.

[!NOTE] Basic Authorization is supported for eStamp, but is less recommended than OAuth 2.0. For production environments, OAuth 2.0 with client credentials should be used.

OAuth 2.0 (eStamp Authentication)

OAuth 2.0 is the recommended authentication method for the eStamp REST API. eStamp exclusively uses the Client Credentials grant type, which means that a machine or system authenticates itself, not a human user. There are no user accounts, passwords, or roles.

Required fields for OAuth 2.0 configuration in eStamp:

Request token (cURL):

# eStamp OAuth 2.0: Request Bearer Token 
# Endpoint: POST /token on the auth server (auth-server-url)
# Prerequesite: Obtain client-id and client-secret from Deployment 
curl -X POST "<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):
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
#   "token_type": "Bearer",
#   "expires_in": 3600
# }
#
# Error 401: client-id oder client-secret incorrect
# Error 404: auth-server-url incorrect

→ Details: [eStamp setup, use, and authentication for PDF signatures: OAuth 2.0]

Bearer token (eStamp access token)

The eStamp bearer token is an OAuth 2.0 access token that must be sent in the Authorization header with every eStamp API call. It is the only Authorization header required by the eStamp API.

Usage:

Authorization: Bearer <token>

Validity period: Specified in the expires_in field of the token response (typically: 3600 seconds = 1 hour). After expiration, the eStamp API returns HTTP 401.

[!WARNING] Security rule: Treat the eStamp bearer token like a password. Never store it in the source code or in plain text. Recommended storage locations: Keycloak, HashiCorp Vault, or a comparable secret store.

Best practices:

• Only make tokens accessible to authorized systems

• Monitor expiration time (expires_in) and proactively renew tokens

• For HTTP 401: First check token validity, then OAuth configuration

Client ID / Client Secret (eStamp OAuth)

client_id and client_secret are the identification data of an application vis-à-vis the eStamp authentication server.

• client_id: The “user name” of the application – the name under which it is registered with the auth server.

• client_secret: The “password” of the application – a secret key known only to the application and the auth server. Together with the client_id, it proves the identity of the application.

[!WARNING] The client_secret must never be stored in the source code or in versioned configuration files.

issuer-uri / auth-server-url (eStamp OAuth)

• issuer-uri: The address of the identity provider (e.g., Keycloak) that issues eStamp tokens. Uniquely identifies who authorizes the tokens.

• auth-server-url: The specific URL to which token requests are sent. Often similar to issuer-uri, but may differ slightly.

Both values are determined and communicated by XiTrust during deployment.

TLS (eStamp connection security)

eStamp uses HTTPS connections exclusively. Supported TLS versions:

C: API Concepts & Workflows

This section explains the basic API concepts and workflow types of the eStamp REST API. Almost all endpoints (exception: XML signature) can be accessed under the base path /signApi/...

eStamp REST API

The eStamp REST API is the standardized HTTP interface for communicating with the eStamp signing service. All calls are made via HTTPS. There are two HTTP methods:

• GET – Retrieve configuration information (e.g., available parameterId values)

• POST – Send documents and trigger signing processes

No exotic protocol: Anyone who has already worked with REST web services is familiar with the principle.

Synchronous workflow (eStamp)

An eStamp synchronous workflow is a single API call that receives a PDF document, signs it immediately, and returns the signed document directly. There is no session, no caching, and no status endpoint.

Process:

1. Send PDF + parameterId via POST

2. eStamp signs synchronously

3. Receive signed PDF as binary response

Available endpoints:

→ See: [eStamp workflow instructions: Synchronous signing (single request)]

Session-based workflow / batch workflow (eStamp)

An eStamp session-based workflow (also known as a batch workflow) is a multi-step process for simultaneously processing multiple documents within a single session. It is used when more than one document needs to be signed at a time.

Order of calls (binding):

[!WARNING] The order is binding. getDocument before seal returns HTTP 404. Retrieve all documents before closeSession – after that, they will no longer be available.

→ See: [eStamp workflow instructions for signing and validating PDF documents: Session-based signing (batch)]

Session (eStamp)

An eStamp session is a temporary processing context for a batch signing operation. It is referenced by a sessionId, which is returned by POST /signApi/startSession.

Important session properties:

[!NOTE] If an incorrect document has been added, a new session must be started—documents cannot be removed after they have been added.

parameterId (eStamp mandatory field)

The parameterId is a mandatory field for every eStamp seal call. It controls which signature handler is used, which certificate is used, and which sealing behavior applies. Without a valid parameterId, the eStamp API returns HTTP 400.

Query available parameterId values:

# eStamp API: Retrieve available parameterId values
# This call should be executed before the first seal process
curl -X GET “https://<host>/estamp/signApi/parameterInfos” \
-H “Authorization: Bearer <token>”
# Successful response (200 OK):
# [{ “parameterId”: “seal”, ‘displayName’: “...”, ... }]
#
# Error 404: Bearer token missing or base URL incorrect

multipart/form-data (eStamp upload format)

multipart/form-data is the HTTP transfer format used by most eStamp endpoints for file uploads. PDF documents, JSON configurations, and string parameters are bundled into a single HTTP request.

Important: Documents must be transferred with Content-Type: application/pdf. Other formats (application/octet-stream, XML, etc.) are rejected by the eStamp API (HTTP 415).

D: Signature visualization

This section explains all concepts related to eStamp signature visualization—i.e., how a signature is visually displayed in a PDF document. Configuration is done using the signatureAppearance JSON object.

[!WARNING] There are two special cases (VisualizationAutomation and signatureFieldId) that are mutually exclusive and must not be combined.

signatureAppearance (eStamp)

The eStamp signatureAppearance is a JSON configuration that specifies how a signature is visually displayed in the PDF – position, size, signature image, and page area. It can be transferred in two ways:

1. As a JSON file directly in the request (sealSingleWithAppearance, addDocumentWithAppearance)

2. As a server-side predefined ID (appearanceId) as a query parameter (sealSingleWithAppearanceParam, addDocumentWithAppearanceParam)

Which mode should be used?

Mandatory fields (standard case):

Optionale Felder (Standardfall):

[!NOTE] Coordinate system: x/y are coordinates, width/height are specified in pt (points) – same logic as in MOXIS.

Complete example JSON (standard case):

{
  "signatureImageId": "amtsSignatur",
  "signaturePageId": "default",
  "firstPage": 1,
  "lastPage": -1,
  "onEveryPage": "",
  "x": 100,
  "y": 100,
  "width": 400,
  "height": 250,
  "signatureAttributes": {
    "subjectDn": "Aussteller"
  }
}

[!WARNING] If onEveryPage: true is set, signaturePageId must not be set.

→ See: [eStamp API Reference and Endpoints: SignatureAppearance]

signatureImageId (eStamp required field)

signatureImageId is a required field in every eStamp signatureAppearance configuration. It references the signature image stored on the server that is to be displayed in the PDF. Without this field, the visualization will not work.

The value must correspond to one of the image IDs configured on the server.

signaturePageId (eStamp)

signaturePageId is an optional field in eStamp-signatureAppearance. It refers to an additional signature page that is appended to the document.

[!WARNING] signaturePageId must not be used together with onEveryPage: true. For VisualizationAutomation, signaturePageId must be set and valid.

signatureFieldId (eStamp – special case)

signatureFieldId is an optional field for the special case where a PDF already contains predefined signature fields. If set, the signature visualization is placed directly in the specified signature field – without manual coordinate specification.

If signatureFieldId is set, these fields are omitted: firstPage, lastPage, onEveryPage, x, y, width, height

Minimal JSON with signatureFieldId:

{
  "signatureImageId": "imageOnly",
  "signatureFieldId": "Signatur2"
}

Query signature field names of a PDF:

# eStamp-API: Determine existing signature fields in a PDF
POST /signApi/signatureFieldNames
# Parameter: document (binary PDF)
# Response: JSON-Array der signatureFieldId-Werte

[!NOTE] IfsignatureFieldId is not set, the position is automatically taken from the first signature field of the PDF.

VisualizationAutomation (eStamp – Special case)

VisualizationAutomation is a special case of the eStamp-signatureAppearance, where the signature visualization is automatically placed at the end of the last text character on the last page. If there is no space above the footer, a new signature page is automatically created.

Required fields in the visualizationAutomation-block:

Example-JSON:

{
  "signatureImageId": "amtsSignatur",
  "signaturePageId": "default",
  "x": 100,
  "width": 400,
  "height": 250,
  "visualizationAutomation": {
    "footerHeight": 6,
    "margin": 10,
    "signaturePageMargin": 60
  }
}

[!WARNING] The following conditions must be met forVisualizationAutomation:

• signaturePageId must be set and valid

• signatureAttributes must not be set

• Cannot be combined with signatureFieldId

signatureAttributes (eStamp – official signature)

signatureAttributes is an optional field in the eStamp-signatureAppearance, that displays additional X.509 certificate attributes in the signature visualization.

[!NOTE] signatureAttributes is only useful for official signatures. This field has no effect on other signature types.

Available certificate attributes:

[!TIP] The left value (key) is technically specified and must not be changed. The right value (display text) can be freely selected.

E – Initials

This section explains the initials function of the eStamp API. Initials are small signature images that are placed on pages of a document to supplement the main signature.

Initials (eStamp)

An eStamp initial is a small signature image that is placed on pages of a document – typically as a side signature. It is configured using a separate JSON configuration (paraphenImage parameter), which can be optionally added to each seal call.

paraphImageId (eStamp required field)

paraphImageId is a required field in the eStamp initials configuration. It references the initials image stored on the server.

Required fields in the initials configuration:

Beispiel-JSON:

{
  "paraphImageId": "picture1",
  "width": 50,
  "height": 22, 
  "x": 10,
  "y": 800
}

ParaphenAppearance (eStamp)

The eStamp-ParaphenAppearance is the server-side configuration of the paraphen appearance (YAML). It is analogous to signatureAppearance, but for paraphen. Available paraphen IDs are queried via GET /signApi/paraphenInfos.

Server-side YAML configuration (example):

estamp:
  paraphen-image:
    picture1: classpath:/paraphenImages/picture1.jpg
    picture2: classpath:/paraphenImages/picture2.png
  paraphen-appearance:
    paraphen1: classpath:/paraphenAppearance/paraphenAppearance1.json
    paraphen2: classpath:/paraphenAppearance/paraphenAppearance2.json

F – Error codes & Operation

This section explains all HTTP status codes, timeouts, and operating concepts of the eStamp REST API. Causes and specific solution steps are provided for each error situation.

HTTP-Statuscodes (eStamp – Übersicht)

HTTP 400 – Bad Request (eStamp)

The eStamp API returns HTTP 400 if the request is invalid.

Common causes:

• parameterId does not exist → call GET /signApi/parameterInfos

• Required fields in signatureAppearance are missing

• Invalid session operation (e.g., addDocument after seal)

Solution steps: Check parameterId, validate JSON configuration against required fields.

HTTP 401 – Unauthorized (eStamp)

The eStamp API returns HTTP 401 if authentication fails.

Common causes:

• Authorization: Bearer <token> header is missing from the request

• Bearer token has expired (expires_in exceeded)

• Token was generated with incorrect client_id/client_secret values

Solution steps:

1. Check whether the Authorization header is set correctly

2. Check expires_in from the token response and request a new token if necessary

3. Verify OAuth configuration (issuer-uri, client-id)

HTTP 404 – Not Found (eStamp)

The eStamp API returns HTTP 404 if an endpoint or resource cannot be found.

Common causes:

• Incorrect base URL or incorrect endpoint path

• Unknown or expired sessionId

• getDocument called before seal

Solution steps: Check the base URL, check the path for upper/lower case, check the session status.

HTTP 422 – Unprocessable Entity (eStamp)

The eStamp API returns HTTP 422 if the PDF document or JSON configuration is invalid.

Common causes:

• PDF is damaged or not a valid PDF/A

• Required fields in signatureAppearance are missing

• Unauthorized combination of special cases (e.g., VisualizationAutomation + signatureAttributes)

Solution steps:

1. Validate PDF with POST /signApi/validatePdf

2. Check JSON configuration against required fields

3. Check special case combination: signatureFieldId and VisualizationAutomation are mutually exclusive

HTTP 500 – Internal Server Error (eStamp)

The eStamp API returns HTTP 500 if an unexpected system error has occurred.

Possible causes: Infrastructure problem, certificate problem, signature creation fails internally.

Solution steps: Check logs, contact support at servicedesk@xitrust.com with: timestamp of the request, endpoint, sessionId (if available), and complete HTTP status code.

Timeout (eStamp)

The eStamp API has two time limits that are often confused:

[!NOTE] A timeout does not mean that the document is corrupted—only that the request took too long.

Retry strategy (eStamp)

In the event of HTTP 429 (Too Many Requests) or a timeout, the following retry strategy is recommended for the eStamp API:

1. Wait briefly: 2–5 seconds
2. Resend the request
3. Avoid aggressive parallelization
4. For batch processing: stagger requests

[!TIP] eStamp is not a streaming system, but is designed for controlled, sequential API calls.

sessionId (eStamp)

The eStamp sessionId is the unique identifier of a batch signing session. It is returned as a JSON string in POST /signApi/startSession and used as a path parameter in all subsequent calls (/{sessionId}/addDocument, etc.).

Important for support requests: If you encounter problems with the batch workflow, always have the sessionId, timestamp, and HTTP status code ready.

G – Tools & Helpful Concepts

This section explains supporting tools and overarching concepts related to the eStamp API.

Swagger (eStamp API test interface)

Swagger is an interactive API documentation platform based on the OpenAPI specification that enables direct testing of eStamp endpoints in the browser. It supports the entire API development lifecycle from design to testing.

Using Swagger with OAuth 2.0:

1. Open the Swagger UI of the eStamp instance

2. Click on the [Authorize] button

3. Enter client_id and client_secret - Bearer token is set automatically

4. Execute API calls directly

Partial Failure (eStamp)

eStamp does not support partial failure. In a batch process, either all documents are signed successfully or the entire process fails. There is no partial processing of individual documents within a session.

Backward Compatibility (eStamp)

eStamp does not implement any breaking changes. Existing integrations remain functional after updates. There are no version dependencies, no hidden system couplings, and no complicated upgrade scenarios. The last 3 versions are actively supported.

If you have any questions, please contact our support team:

XiTrust Support Team | servicedesk@xitrust.com | Create a service desk ticket