Skip to content
TimeLogic API logoTimeLogic API
Sign in

Signed time API: signed responses and Ed25519 verification

Signed time API with verifiable timestamps: add sign=true and each response carries an Ed25519 signature over the exact body, path and signing time.

Updated

Short answer: add sign=true. The response body stays exactly the same, and headers carry an Ed25519 signature over those exact bytes. Verify it locally with the public key from https://api.timelogicapi.com/.well-known/time-api-public-key.

What is a signed time API?

A signed time API returns the time together with a signature from the provider's private key, so the value can be checked later by anyone with the matching public key. TimeLogic API is a signed time API: add sign=true to a supported request and the response carries a detached Ed25519 signature. The time it reports becomes a verifiable timestamp you can store, forward and re-check, instead of a number you have to take on trust.

The signature covers a short envelope: the HTTP status, the method, the request path and query, the Unix time the signature was produced, and the SHA-256 of the exact body. Change any of those and verification fails, which is what makes the stored response tamper-evident.

How do signed API responses work?

Add sign=true to a supported JSON route for signed API responses. TimeLogic API leaves the JSON body unchanged and returns headers containing the key id, algorithm, timestamp, body hash, signing input, and Ed25519 signature.

Verify the exact response bytes locally against the public key from https://api.timelogicapi.com/.well-known/time-api-public-key (no API key needed); this is the Ed25519 API response verification workflow. The browser signed-response verifier helps inspect a response without sending it to a third party.

How do I verify a signed response?

  1. Request the public key registry from https://api.timelogicapi.com/.well-known/time-api-public-key and select the key named by the response's X-TimeLogic-Key-Id header (or the kid inside the signed input).
  2. Preserve the exact response body bytes. Do not parse and re-serialize JSON before verifying. Compute their SHA-256 and compare it with X-TimeLogic-Content-SHA256.
  3. Decode the X-TimeLogic-Signature-Input header (Base64URL, UTF-8) and check that its content-sha256 line matches the body hash. Use the decoded bytes exactly as received; do not rebuild the signing input yourself.
  4. Verify the Ed25519 signature in X-TimeLogic-Signature over those decoded bytes with the public key, then process the JSON.

For a service integration, use an Ed25519 library in your server language and keep the public key registry refreshable so key rotation can be handled.

Where do verifiable, tamper-proof timestamps help?

  • Audit logs and compliance records: keep the signed response next to the event, so a reviewer can check when your system asked for the time and what it was told.
  • Deadlines, cut-offs and expiry checks: prove which side of a deadline a request fell on, using a trusted time API instead of a client clock that can be wrong or changed.
  • Business-day and holiday results: a signed business-days answer records which calendar result your system acted on.
  • Data passed between services: a downstream service can verify the time value without calling the API again.

What it does not do: TimeLogic signs its own responses. It is not an RFC 3161 timestamp authority and does not timestamp documents you upload.

Which routes support signing?

Signing is supported for current time, conversion, difference, add, calendar, DST, elapsed, and timezone JSON routes. /v1/time/clock does not support signing.

The WorldTimeAPI-compatible routes accept sign=true too, on JSON and on .txt responses. Their body stays byte-identical to the unsigned WorldTimeAPI-format response, so existing parsers are unaffected; the signed path includes the .txt suffix when the text form was signed.

Related guides and documentation

Frequently asked questions

What is a signed time API?

A signed time API returns the time together with a cryptographic signature, so anyone holding the provider's public key can check later that the value really came from that API and was not changed. With TimeLogic API you add sign=true and the response carries an Ed25519 signature over the exact body, the HTTP status, the method, the request path and the signing timestamp.

How do I request a signed response?

Add sign=true to a supported route. The body is unchanged and six response headers carry the key id, algorithm, timestamp, body hash, signing input and Ed25519 signature.

Can I use signed responses as verifiable or tamper-proof timestamps?

Yes, within what the signature covers. Store the raw body with the six signature headers; anyone can later re-check the body hash and the Ed25519 signature against TimeLogic's published key. Changing a single byte of the body, the status, the path or the signing timestamp makes verification fail.

Is this an RFC 3161 timestamp authority?

No. TimeLogic signs its own HTTP responses with Ed25519 detached signatures and publishes the keys as a JWKS. It does not issue RFC 3161 timestamp tokens for documents you upload.

Where do I get the public key?

From https://api.timelogicapi.com/.well-known/time-api-public-key. No API key is needed. Select the key named by the X-TimeLogic-Key-Id header.

Why must I verify the raw bytes instead of parsed JSON?

The signature covers the exact response body bytes through their SHA-256 hash. Parsing and re-serializing JSON can change those bytes, so verify first and parse afterwards.

Which routes support signing?

The current time, conversion, difference, add, calendar, DST, elapsed and timezone JSON routes, and the WorldTimeAPI-compatible /api routes on both JSON and .txt responses. /v1/time/clock does not support signing.