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:

sign_response=true

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. Get the key_url in the header,

2. Fetch the key (see Get a key),

3. Check if the deprecated field is null,

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

/sign-keys

Get a key

GET /sign-keys/{key_id}

Keys format

Property	Type	Description
id	Number	ID of the key.
public_key	String	PEM of the public key.
deprecated	DateTime or null	If set, this key is deprecated and any signature using it should not be trusted.