eStamp: FAQs about authentication, workflows, limits, and error codes

Content

This document answers frequently asked questions about the eStamp REST API, organized by topic. Each question is formulated as a separate unit and contains the complete context for the answer. Prerequisites for using the eStamp REST API: a valid, customer-specific eStamp base URL and a valid bearer token (OAuth 2.0 or Basic Authorization).

1. Architecture and basic concepts

What base URL does an eStamp instance receive?

Each eStamp instance receives its own customer-specific base URL during deployment. The format is https://estamp.<kundenname>.xitrust.cloud/estamp. The base URL is determined by the XiTrust support team and communicated during deployment. Without the correct eStamp base URL, all API calls will fail with at 404 Not Found error. If an eStamp service is unavailable, the base URL is the first thing to check.

Does eStamp have a client model?

eStamp does not have a client model. There are no separate clients within an eStamp instance. Different configurations—for example, different certificates, signature types, or signature visualizations—are mapped within an instance via signature handlers. This allows multiple organizational units to operate with different configurations without requiring their own instance. For complete technical separation, a separate eStamp instance is recommended.

Is there API versioning in eStamp?

eStamp does not use URL-based API versioning such as /api/v1/ or /api/v2/. Instead, XiTrust guarantees that no breaking changes will be made to the eStamp REST API. Existing integrations will continue to function after updates. The last two eStamp versions are actively supported. Special compatibility management is therefore not necessary.

What is the eStamp REST API and which protocols are used?

The eStamp REST API is the interface through which all signing, sealing, and validation operations are performed. Communication takes place exclusively via HTTPS using the standard HTTP methods GET (retrieve information) and POST (send document, trigger signature). No proprietary or exotic protocols are used. The base path of all eStamp signature endpoints is /signApi/....

2. Authentication and Security

What authentication methods does eStamp support?

eStamp supports two authentication methods: OAuth 2.0 and Basic Authorization. Both methods protect all eStamp endpoints that process documents. No signing or sealing operations will be accepted without valid authentication. OAuth 2.0 is the recommended method for all new eStamp integrations.

What is the eStamp bearer token and how is it used?

The eStamp bearer token is an access token obtained from the configured authentication server via the OAuth 2.0 flow (grant type: client credentials). The Bearer Token is sent in the Authorization-header with every eStamp API call: Authorization: Bearer <token>. The token has a limited validity period (expires_in). After expiration, the eStamp API returns 451 Unavailable for Legal Reasons zurück. Integrations should implement automatic token renewal before the expiration date.

[!IMPORTANT] The eStamp bearer token must be treated like a password. client_id, client_secret and bearer tokens 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).

Which TLS version does eStamp require?

eStamp requires at least TLS 1.2. The standard is TLS 1.3. Connection attempts with older TLS versions are rejected. All connections to the eStamp REST API are therefore encrypted and comply with current security standards.

Are all eStamp endpoints protected equally?

No, eStamp distinguishes between protected and unprotected endpoints. Only license information endpoints are accessible without protection, as this information is not security-relevant. All endpoints that process documents—i.e., signing, sealing, and session operations—are protected with OAuth 2.0 or Basic Authorization.

Any validly authenticated client can use all protected eStamp endpoints; there is no RBAC, no user roles, and no different authorization levels.

3. Workflows: Synchronous and session-based

What is the difference between synchronous and session-based workflows in eStamp?

The synchronous eStamp workflow processes a single document per API call: The document is sent and the signed result is returned immediately — without sessions, caching, or status queries. The session-based workflow enables batch processing of multiple documents in a multi-step process (startSession → addDocument → seal → getDocument → closeSession). The synchronous workflow is simpler for individual documents; the session-based workflow is necessary for batch processing of up to 100 documents per session.

Are there background processes or a status endpoint in eStamp?

eStamp does not use background processes, status endpoints, polling, or webhooks. Each eStamp API call blocks until it is completely finished and returns the result directly. This applies to both synchronous calls and the seal-step in the session-based workflow..

How many documents can be processed per eStamp session?

A maximum of 100 documents can be processed per eStamp batch session. The same limit applies per individual REST call. If more than 100 documents need to be signed, multiple sessions must be started. The number of sessions running simultaneously is not limited. Only one session can be started per REST call.

Is the eStamp session-based workflow a true asynchronous model?

No, the session-based eStamp workflow is not an asynchronous model. Every call - including seal - blocks until it is completed. There is no status endpoint, no job ID, and no webhook. Once seal is complete, getDocument can be called.

How long is an eStamp session valid?

An eStamp batch session is valid for 40 minutes from the startSession call. If the session is not terminated with closeSession within this time, it expires automatically. A single API call within the session may take a maximum of 30 seconds. If this time is exceeded, the call is aborted and an error message is returned. A timeout does not necessarily mean that the document is damaged, but rather that the call took too long.

What happens when an eStamp API call times out or is canceled?

If an eStamp API call times out or is canceled, the process is terminated and an error message is returned. No partial processing takes place. Expired or unfinished eStamp sessions are automatically cleaned up—no manual cleanup is required.

Can documents be removed or replaced from an eStamp session after they have been added?

No. Once documents have been added to an eStamp session, they cannot be removed or replaced. If an incorrect document has been added, a new eStamp session must be started using startSession.

Is there partial failure in eStamp batch processing?

eStamp does not support partial failure. A batch operation is either completely successful or completely fails. There is no partial processing of individual documents within a session.

4. Limits and performance

What technical limits apply to the eStamp REST API?

The following limits apply to the eStamp REST API: a maximum of 100 documents per session and per REST call, a timeout of 30 seconds per individual API call, a session validity of 40 minutes from startSession, and a maximum file size that is defined instance-specifically in the system configuration. The maximum file size is not fixed and may vary depending on the eStamp instance.

What rate limits are there for eStamp?

eStamp does not define a publicly specified rate limit (e.g., “X requests per second”). Too many simultaneous requests can result in extended response times, timeouts, or HTTP 429 Too Many Requests eStamp is designed for controlled, sequential API calls and is not a streaming system. Aggressive parallelization should be avoided.

What does HTTP 429 mean at eStamp and how should you respond to it?

HTTP 429 Too Many Requests signals that too many requests were sent in a short period of time or that the document limit for a session has been reached. The recommended retry strategy is to wait 2–5 seconds and then resend the request. Batch processing should be staggered for high volumes.

5. 5. File upload and file formats

Which file formats does eStamp accept for uploads?

eStamp only accepts application/pdf for document uploads. Other formats such as application/octet-stream, XML, or other document types are not accepted for PDF signature endpoints and result in a 415 Unsupported Media Type. XML documents can be validated via the separate endpoint POST /xmlSignApi/validateXml.

Is there a maximum file size for eStamp?

Yes, but the maximum file size is not globally fixed. It is defined in the system configuration of the respective eStamp instance and can therefore vary depending on the deployment. If an uploaded document exceeds the configured limit, eStamp returns 413 Payload Too Large.

What restrictions apply to PDF documents to be uploaded?

eStamp does not restrict the number of pages or the PDF variant. All common PDF variants — including PDF and PDF/A — are processed. Temporary files are stored in encrypted form during processing. Signature control and visualization

Which parameter controls signature behavior in eStamp?

Signature behavior in eStamp is controlled by the parameterId. The parameterId is a mandatory field for every seal call and determines which signature handler is used, which certificate is used, and which sealing behavior applies. The available parameterId-values for an eStamp instance are queried via GET /signApi/parameterInfos.

How is the signature visualization (signatureAppearance) transferred to eStamp?

The signatureAppearance configuration can be transferred in two ways: as a JSON file when calling sealSingleWithAppearance or addDocumentWithAppearance, or as a server-side stored ID (appearanceId) when calling sealSingleWithAppearanceParam or addDocumentWithAppearanceParam. The format of the signatureAppearance configuration is always JSON.

Are signature attributes (signatureAttributes) configurable in eStamp?

Yes, additional X.509 certificate attributes can be displayed in the signature visualization using the optional signatureAttributes - for example, subjectDn, serialNumber or notAfter. The signatureAttributes are linked to the official signature and only make sense when used with official signatures. The field should not be set for other signature types.

What unit does the coordinate system of the eStamp signature visualization use?

The position specifications x and y describe the coordinates of the signature visualization on the PDF page. The size specifications width and height are given in pt (points). Default values: width = 400, height = 270.

7. Error codes and debugging

Which HTTP status codes does eStamp use?

eStamp uses standard HTTP status codes. The following table shows the most important codes, their meanings, and typical causes:

What do eStamp error responses look like?

eStamp returns errors with an HTTP status code and an error message. There is no additional uniform JSON error schema — the error information is contained in the HTTP status code and the associated message.

How do I debug eStamp errors via response headers?

eStamp requests can be tracked via the request ID in the response header. The request ID enables internal mapping to log entries, but does not itself contain any error information. The following information is helpful for support requests: timestamp of the request, endpoint used, sessionId (if available) and complete HTTP status code.

What are the most common causes of errors with eStamp?

In the majority of cases, eStamp errors can be traced back to four causes: an incorrect or invalid parameterId (400), an expired or missing bearer token (401/451), a document that is too large (413), or an invalid or damaged PDF (422). The quick diagnosis for operations and administration: 400 errors indicate configuration problems, 401/403 indicate authentication problems, 413 indicate file size problems, and 500 indicate system problems.

What to do in case of an HTTP 500 Internal Server Error from eStamp?

HTTP 500 Internal Server Error signals an unexpected system error in eStamp — for example, an infrastructure problem, a certificate problem, or a failed signature creation. Check the eStamp server logs using the timestamp and session ID. If you cannot resolve the problem yourself, contact the XiTrust support team at servicedesk@xitrust.com with the timestamp, endpoint, sessionId and HTTP status code.

Quick reference: Rapid diagnosis of eStamp errors

If an eStamp API call fails, we recommend the following sequence for error diagnosis:

1. Check HTTP status code: Indicates the error type (see table above)

2. Check bearer token: Is the token valid and not expired?

3. Check parameterId: Does the value exist in GET /signApi/parameterInfos?

4. Check base URL: Is the customer-specific eStamp base URL correct?

5. Check file size: Does the document exceed the configured limit?

6. Check logs: Track using timestamp and sessionId in the eStamp server logs.