---
title: "Timestamp a PDF - PKI Express"
description: "How to add a timestamp to a PDF with PKI Express: the PadesTimestamper class, the timestamp authority (such as Rest PKI's, with an access token) and the output file."
canonical: "https://docs.lacunasoftware.com/en-us/articles/pki-express/timestamp-pdf"
locale: "en"
product: "PKI Express"
last_updated: "2026-10-12"
---

# Timestamp a PDF - PKI Express

[PKI Express](https://docs.lacunasoftware.com/en-us/articles/pki-express) can add a timestamp to a PDF, which proves that the file existed as it is at that moment. The samples add a
document timestamp with the `PadesTimestamper` class, using Rest PKI's timestamp authority. 
This needs PKI Express 1.7.0 or later, which added the `stamp-pdf` command. 

The code is Python, from the [PKI Suite samples](https://github.com/LacunaSoftware/PkiSuiteSamples), with the `pkiexpress` package (1.10.4);
the Node.js sample does the same. 

## Flow

1. Create a `PadesTimestamper` and give it a timestamp authority.
1. Set the PDF and the path of the output file.
1. Call `stamp()`, which runs PKI Express's `stamp-pdf` command and writes the timestamped PDF to the output path.

```python
stamper = PadesTimestamper()
set_pki_defaults(stamper)
stamper.set_pdf_from_path(join(current_app.config['APPDATA_FOLDER'],
                               file_id))
create_app_data()  # Guarantees that "app_data" folder exists.
output_file = '%s.pdf' % str(uuid.uuid4())
output_file_path = join(current_app.config['APPDATA_FOLDER'], output_file)
stamper.output_file_path = output_file_path
stamper.stamp()
```

* Instead of an output path, you can set `overwrite_original_file` to stamp the PDF in place. 
* The PDF can also be given as bytes (`set_pdf_from_raw`) or Base64 (`set_pdf_from_base64`). 
* `stamp()` returns nothing: read the result from the output file. 

The class has the same name in the other client libraries; the methods differ: 

| Library | Input PDF | Output file | Stamp |
|---|---|---|---|
| Node.js | `setPdfFromPath(path)` (returns a Promise) | `setOutputFilePath(path)` | `stamp()` (returns a Promise) |
| Java | `setPdf(path)` | `setOutputFilePath(path)` | `stamp()` |
| PHP | `setPdfFromPath($path)` | `setOutputFile($path)` | `stamp()` |
| Python | `set_pdf_from_path(path)` | `output_file_path` property | `stamp()` |

A visible representation of the timestamp is available in PKI Express 1.18.0 and later, through `setVisualRepresentation` in the Node.js,
Java (1.23.1) and PHP libraries. 

## The timestamp authority

The samples set the timestamp authority in a helper that every operator goes through. They use Rest PKI's timestamp authority,
authenticated with the Rest PKI access token, and set it only when a token is configured: 

```python
if current_app.config['REST_PKI_ACCESS_TOKEN'] is not None:
    authority = TimestampAuthority('https://pki.rest/tsp/a402df41-8559-47b2-a05c-be555bf66310')
    authority.set_oauth_token_authentication(current_app.config['REST_PKI_ACCESS_TOKEN'])
    operator.timestamp_authority = authority
```

* To get a Rest PKI access token, see [Requesting timestamps to Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/requesting-timestamps). 
* Other timestamp authorities can authenticate with a user and password (`set_basic_authentication`) or with an SSL client certificate,
  identified by its thumbprint (`set_ssl_authentication`; Java: `setSSLThumbprint`). See [Configuring Timestamp Authority](https://docs.lacunasoftware.com/en-us/articles/pki-express/php/configuring-timestamp-authority)
  for the PHP version. 
* The Python library sends a timestamp request timeout (`request_timeout`, default 15), and the Node.js library always sends 15; both
  need PKI Express 1.12.2, which added the timeout. 
  TODO(docs): the unit of the timestamp request timeout.
* TODO(docs): what `stamp-pdf` does when no timestamp authority is set (the samples set one only when a Rest PKI token is configured).

## Errors

If the timestamp authority fails, PKI Express returns code 30 (`TimestampAuthorityNotAvailable`); code 32 (`TimestampOptionsRequired`)
means that no timestamp authority address was given. See [Return codes](https://docs.lacunasoftware.com/en-us/articles/pki-express/return-codes). 

## See also

* [Validate signatures](https://docs.lacunasoftware.com/en-us/articles/pki-express/validate-signatures), to inspect the timestamped file
* [PKI Express quick reference](https://docs.lacunasoftware.com/en-us/articles/pki-express/quick-reference)
* [Rest PKI Core](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core), whose cloud service also timestamps PDFs 

**Demos and samples**

- Live demo: [Timestamp a PDF](https://try.lacunasoftware.com/en/pki-suite/timestamp-a-pdf)
- Timestamp a PDF with PKI Express: [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/timestamp-pdf-express.js) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/timestamp_pdf_express.py)