Skip to main content
The JWKS (JSON Web Key Set) endpoint provides the public keys used by the VCVerifier to sign JWTs. These keys are essential for verifying the authenticity of tokens issued by the verifier.

​
Endpoint

GET /.well-known/jwks

​
Overview

This endpoint returns a JSON Web Key Set (JWKS) containing one or more public keys that can be used to verify JWTs signed by the VCVerifier. The endpoint follows the standard JWKS format as defined in RFC 7517.
The JWKS endpoint is publicly accessible and does not require authentication. It’s designed to be used by clients that need to verify tokens issued by this verifier.

​
Response

The endpoint returns a JWKS object containing an array of public keys.

​
Response Schema

​
keys
array
required
An array of JSON Web Key objects
​
kid
string
Key ID - A unique identifier for the keyExample: 179d7b56-6598-4045-9a32-4635e8b0f605
​
kty
string
Key Type - The cryptographic algorithm family used with the keySupported values: EC (Elliptic Curve), RSAExample: EC
​
use
string
Public Key Use - Identifies the intended use of the public keyTypical value: sig (signature)
​
alg
string
Algorithm - The algorithm intended for use with the keyExample: ES256 (ECDSA using P-256 and SHA-256)
​
crv
string
Curve - The elliptic curve used with the key (for EC keys)Example: P-256
​
x
string
X Coordinate - The x coordinate for the Elliptic Curve point (for EC keys)Example: 3ctHY_0KJW5ezT-oF39t3wPX6XlggWKOSPFW8iooBXk
​
y
string
Y Coordinate - The y coordinate for the Elliptic Curve point (for EC keys)Example: HXA4mBHgObIE56E92yxN5bYQ27wSxlVPfuNWaY06TTI
​
n
string
Modulus - The modulus value for RSA keys
​
e
string
Exponent - The exponent value for RSA keys
​
d
string
Private Key Component - Not included in JWKS responses (private key parameter)

​
Response Example

{
  "keys": [
    {
      "kid": "179d7b56-6598-4045-9a32-4635e8b0f605",
      "kty": "EC",
      "use": "sig",
      "alg": "ES256",
      "crv": "P-256",
      "x": "3ctHY_0KJW5ezT-oF39t3wPX6XlggWKOSPFW8iooBXk",
      "y": "HXA4mBHgObIE56E92yxN5bYQ27wSxlVPfuNWaY06TTI"
    }
  ]
}

​
Key Types

The VCVerifier supports the following key types:

​
Elliptic Curve (EC) Keys

EC keys are the primary key type used by the verifier:
  • Algorithm: ES256 (ECDSA using P-256 curve and SHA-256)
  • Curve: P-256 (also known as secp256r1)
  • Key Components: x and y coordinates
Elliptic Curve keys provide strong security with smaller key sizes compared to RSA, making them efficient for JWT signing operations.

​
RSA Keys

RSA keys are also supported:
  • Key Components: Modulus (n) and public exponent (e)
  • Common algorithms: RS256, RS384, RS512

​
Usage

Clients should fetch the JWKS periodically or cache it with appropriate cache headers. When verifying a JWT:
  1. Extract the kid (Key ID) from the JWT header
  2. Find the matching key in the JWKS by comparing the kid values
  3. Use the public key parameters to verify the JWT signature
  4. Ensure the alg in the JWT header matches the key’s algorithm
const response = await fetch('https://verifier.example.com/.well-known/jwks');
const jwks = await response.json();

// Find key by kid
const key = jwks.keys.find(k => k.kid === tokenHeader.kid);

// Verify JWT using the key
// (implementation depends on your JWT library)

Build docs developers (and LLMs) love

Get started for freeTalk to us