Response signature

The API can generate JWS tokens instead of JSON responses.
This may be useful if you or one of your clients needs to assert
  • the data's origin,
  • which request was used exactly,
  • the timestamp the request was executed at.
Signed responses need to be enabled. Contact us.

Get signed responses

To get a signed response, add the following query parameter to your request:

Token format

As any JWS, the structure is header.payload.signature, where
  • header is a base64-encoded JSON with information about the signature process (see Verify token signature),
  • payload is a base64-encoded JSON with the following structure:
    "request_url": ...,
    "response_timestamp": ...,
    "response_payload": ...,
  • signature is a base64-encoded bytes section.

Verify token signature

  1. 1.
    Get the key_url in the header,
  2. 2.
    Fetch the key (see Get a key),
  3. 3.
    Check if the deprecated field is null,
  4. 4.
    Use the public_key field to check the signature using your favorite JWS library.

Keys resource

List keys

The list of past and present keys can be obtained at

Get a key

GET /sign-keys/{key_id}

Keys format

ID of the key.
PEM of the public key.
DateTime or null
If set, this key is deprecated and any signature using it should not be trusted.