---
title: "Publish keys as JWKS: a guide for issuers"
url: https://knowyouragent.ch/en/knowledge/guides/publish-keys-as-jwks
lang: en
updated: 2026-10-17
license: © Innopulse Consulting GmbH
---

# Publish keys as JWKS: a guide for issuers

Verifying parties can verify evidence only if they know the issuer's public key. A JSON Web Key Set (JWKS) at a fixed address is the usual way. This guide shows creation, publication and rotation.

[Leutrim Miftaraj](https://knowyouragent.ch/en/about/leutrim-miftaraj), Founder, Innopulse Consulting GmbH
Published 17 October 2026

## Key points

- Verifying parties need the issuer's public key, usually as JWKS.
- Every piece of evidence names its key ID so the right key is found.
- During rotation, the old key stays in the JWKS until all evidence signed with it has expired.

## Create a key pair

Create a key pair for ES256 (ECDSA with P-256). The following Node.js script writes the public key as JWKS and the private key to a protected file:

```
import { generateKeyPairSync } from "node:crypto";
import { writeFileSync } from "node:fs";

const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
const kid = "issuer-2026-10";
const jwk = { ...publicKey.export({ format: "jwk" }), kid, alg: "ES256", use: "sig" };
writeFileSync("jwks.json", JSON.stringify({ keys: [jwk] }, null, 2));
writeFileSync("private.pem", privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
```

In production, the private key belongs in a hardware security module or a managed key service, not in a file.

## Check the JWKS

The JWKS created contains only public details: key type, curve, coordinates, key ID, algorithm and intended use.

```
{
  "keys": [
    { "kty": "EC", "crv": "P-256", "x": "…", "y": "…", "kid": "issuer-2026-10", "alg": "ES256", "use": "sig" }
  ]
}
```

Make sure the d field, the private part, never appears in the JWKS.

## Publish the JWKS

Serve the JWKS at a fixed HTTPS address, for example at /.well-known/jwks.json on your domain, and name the address in your evidence or documentation. Verifying parties load the JWKS once from this trusted source and provide it; KYA does not load keys from the network itself.

## Set the key ID in evidence

Enter the key ID in the header of every signed piece of evidence as kid. This lets the [verifying party](https://knowyouragent.ch/en/knowledge/glossary/verifying-party) find the right key even if the JWKS contains several. A kid that matches no key provided is reported by the engine with the code no_key.

## Rotate keys

To rotate, create a new key with a new kid and add it to the JWKS. Sign new evidence with the new key, but leave the old one in the JWKS until all evidence signed with it has expired. If a key is compromised, remove it immediately and revoke affected evidence through the [status list](https://knowyouragent.ch/en/knowledge/guides/publish-a-status-list).

## Troubleshooting

If a verifying party reports no_key, the kid in the evidence matches no key in its JWKS; usually the new key is missing after a rotation. If it reports signature_invalid, the evidence was signed with a different private key than the one belonging to the kid, or the content was altered. Also check that the algorithm in the header and the key type match.

## Frequently asked questions

### Which algorithm is recommended?

ES256 is widespread and compact. EdDSA with Ed25519 is also well suited but is not supported by every environment.

### May I use the same key for mandates and status lists?

Technically yes. Separate keys with their own kid make rotation easier, however, and limit the damage if a key is compromised.

### How long should a key be valid?

One to two years is common. Shorter periods limit the risk but require more frequent rotation and good automation.

### How do verifying parties learn about a new key?

Through the updated JWKS at the same address. Also announce rotations so verifying parties provide the new key in time.

### Must the JWKS be publicly reachable?

For verifying parties outside your company, yes. It contains only public keys and may therefore be retrievable without sign-in.

## Sources

- RFC 7517: JSON Web Key (JWK): [https://www.rfc-editor.org/rfc/rfc7517](https://www.rfc-editor.org/rfc/rfc7517)
- RFC 7518: JSON Web Algorithms (JWA): [https://www.rfc-editor.org/rfc/rfc7518](https://www.rfc-editor.org/rfc/rfc7518)

---
Quelle: https://knowyouragent.ch/en/knowledge/guides/publish-keys-as-jwks · KYA – Know Your Agent