Skip to main content

Get a signing key

GET 
https://api.dilisense.com/v1/keys/{kid}

The keys API method returns the public key for a key ID as a JSON Web Key.

A signed HTTP message from dilisense carries an x-dilisense-signature header next to its unchanged JSON body. The signature lets you verify that the body originates from dilisense and was not altered on its way to you, for example by a proxy, and it lets you prove later, for example in an audit, what dilisense sent. Verification is optional, clients that ignore the header keep working unchanged.

The header value consists of comma-separated parts: v1,kid=<key id>,sig=<signature>

  • v1: the version of the signature scheme.
  • kid: the ID of the key that created the signature. Use it to fetch the public key from the keys endpoint.
  • sig: the signature, base64url-encoded without padding (RFC 4648 section 5).

Signatures are created with ES256, i.e. ECDSA on the NIST P-256 curve (also known as secp256r1 or prime256v1) with SHA-256 as the hash function. The signed data are the exact UTF-8 bytes of the HTTP body as transmitted.

Key rotation. The signing key is rotated regularly, every key is used for signing for a limited period and is then retired. Keys stay retrievable by their ID after their retirement, so that you can verify a stored body at any later point in time. Follow these rules in your implementation:

  • Look up the key by the kid of the signature header, never rely on current for verification. The current key can change between the moment a body is signed and the moment you fetch the key.
  • Do not hardcode a key. Fetch a key the first time you see its ID and cache it by ID. The key material of a key document never changes, only its status does, so refresh cached keys from time to time to notice a revocation.
  • Accept the statuses ACTIVE and RETIRED, reject REVOKED.

Request​

Responses​

Error responses are the same for all endpoints, see Errors.

Example​

Request​

curl --location --request GET 'https://api.dilisense.com/v1/keys/current' \
--header 'x-api-key: <api_key>'

Response​

{
  "status": "ACTIVE",
  "not_before": "2026-09-07T03:00:12.482Z",
  "not_after": "2026-09-21T03:00:12.482Z",
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "kid": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "x": "bKTx6DOR16BCmP_2pCIzfjjIuegFlS6Y3wsWH12Wr8o",
      "y": "stY6VDFgVicJQnpBn763CwilIJBbDoy4sLg7Hsq1vP0"
    }
  ]
}