Before you can request a document to be timestamped, make sure the feature is activated on your account.
Universign operates a qualified timestamping authority and offers two ways to obtain a timestamp: as part of a PAdES signature process (below), or as a standalone RFC 3161 token for any data, independently of a signature process (see Request an RFC 3161 timestamp).
Request a PAdES timestamp
To request a timestamp, send a multipart/form-data request to POST /v1/timestamp/pades and pass the document in the file argument.
Note that we accept only PDF input format in a maximum size limit of 25MB.
curl
https://api.universign.com/v1/timestamp/pades \
-F [email protected]
The API returns a 200 response that contains a PAdES document timestamp compliant with the ETSI TS 119 142-3 standard.
Access to this endpoint requires the timestamping service entitlement.
Request an RFC 3161 timestamp
The RFC 3161 endpoint lets you obtain a timestamp token for any data, independently of a signature process: you send the hash of your data, you receive a signed token proving that this exact data existed at that exact time. This endpoint implements the standard Time-Stamp Protocol defined by RFC 3161, so any RFC 3161-compliant tool or library can build the request and verify the response.
Access to this endpoint requires the RFC 3161 timestamping service entitlement.
What you can do with it
- Timestamp a document without signing it.
- Prove the existence date of any data at a given time - logs, archives, source code, database extracts.
- Add a trusted date to a workflow driven by your own application.
Your data never leaves your system: you only send its hash.
Send the request
POST /v1/timestamp/rfc3161
| Authentication | Workspace API key |
| Content-Type | application/timestamp-query |
| Accept | application/timestamp-reply |
| Body | A DER-encoded RFC 3161 TimeStampReq |
The request body must be a binary TimeStampReq containing:
| Field | Description |
|---|---|
version |
Always 1 |
messageImprint |
The hash algorithm identifier and the hash of your data |
nonce |
Optional. A random value returned as-is in the response, to protect against replay |
certReq |
Set to true to receive the certificate chain in the response. Recommended - it is required to verify the token offline |
Supported hash algorithms:
- SHA-1
- SHA-256
- SHA-384
- SHA-512
Build a request with OpenSSL:
openssl ts -query -data mydocument.pdf -sha256 -cert -out request.tsq
Then send it:
curl -X POST https://api.universign.com/v1/timestamp/rfc3161 \
-H "Content-Type: application/timestamp-query" \
-H "Accept: application/timestamp-reply" \
-u "your-api-key:" \
--data-binary @request.tsq \
--output response.tsr
Read the response
The response body is always a DER-encoded TimeStampResp, even when the request is refused. It contains:
- a
PKIStatusInfogiving the outcome, - when granted, a
TimeStampToken- a CMSSignedDatastructure holding the timestamp itself and, ifcertReqwas set totrue, the certificate chain.
Inspect the response with OpenSSL:
openssl ts -reply -in response.tsr -text
Errors
The response body is never JSON. Every outcome, including errors, is returned as an ASN.1 TimeStampResp. The HTTP status tells you the category of the problem:
| HTTP status | Meaning | What to do |
|---|---|---|
200 |
The timestamp was granted | Store the token |
401 |
No valid credentials were provided | Check your API key |
403 |
Your workspace does not hold the RFC 3161 timestamping service entitlement | Contact your account manager |
400 |
The request could not be read, or the timestamping authority rejected it as invalid | Check that your TimeStampReq is well formed and uses a supported hash algorithm |
500 |
The timestamping authority is unavailable or returned an unusable response | Retry later |
In every case, the PKIStatusInfo of the response carries a PKIFailureInfo code and a free-text message describing the cause.
Verify a timestamp token
A token issued by this endpoint is a standard RFC 3161 token. You can verify it offline, with any RFC 3161-compliant tool, as long as you requested certReq=true.
Follow your consumption
Each granted timestamp counts as one unit of RFC 3161 timestamping consumption. Refused requests - malformed, unauthorised, or rejected by the timestamping authority - are never counted.
RFC 3161 timestamps are reported on a dedicated line in your consumption report, and are also included in your total timestamping consumption, alongside timestamps produced by signature processes. See Retrieve consumption report.
