> For the complete documentation index, see [llms.txt](https://docs.corppass.gov.sg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/jwks-endpoint.md).

# JWKS Endpoint

The **JSON Web Key Set (JWKS) Endpoint** hosts the **Public Signing Keys** used by Corppass.

Corppass signs all sensitive tokens (including the ID Token and Userinfo Response) using a dedicated private key. To validate the integrity and authenticity of these tokens, Relying Parties (RPs) must retrieve the corresponding public key from this endpoint.

## Request

Dynamically obtain this URL from the [OpenID Discovery Endpoint](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/openid-discovery-endpoint.md) (`jwks_uri`).

```http
GET /.well-known/keys
```

## Response

The response is a JSON object containing an array of keys (`keys`). Each key follows the JSON Web Key (JWK) specification.

{% hint style="info" %}
**Performance Note: Caching**

Responses from this endpoint, or individual keys within the JWKS, should be cached by the RP for at least 1 hour to avoid retrieving the JWKS for every JWT validation.
{% endhint %}

### Sample Reponse

```http
HTTP/2 200
content-type: application/jwk-set+json; charset=utf-8
content-length: 955
{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "kid": "OvNklZwNmhiE6tu9mtWTDAv218k2DMjuRaGhkBgFdOo",
      "alg": "ES256",
      "crv": "P-256",
      "x": "gnbm-h8k3ZzeegHK0x87wO_SP_MLFts9XPZm7pE8U04",
      "y": "JvtZtPUqAS6837asiImtx-oO05wQS-Z6lOneq9zi_qQ",
    }
  ]
}

```

## How to Validate a Signature

This endpoint returns one or more public keys in JSON Web Key (JWK) format.

To validate a JWT signature, your application (or OIDC library) must follow these steps:

1. **Extract Header:** Parse the JOSE Header of the received JWT (ID Token or Userinfo).
2. **Read Key ID:** Note the `kid` (Key ID) value in that header.
3. **Find Key:** Look up the key in the JWKS response where the `kid` matches the token's `kid`.
4. **Check Usage:** Ensure the matched key has the attribute `"use": "sig"` (that indicates a signing key).
5. **Verify:** Use this public key to verify the JWT signature.

## Key Rotation

Corppass reserves the right to rotate / update its signing keys at any time, and without prior notice.

**When a key rotation occurs:**

1. New keys will be published to the JWKS endpoint, each with a unique `kid` value.
2. JWTs issued after the rotation will reference the updated `kid` in their JOSE headers.
3. RPs must refresh their cached JWKS by querying the JWKS endpoint to retrieve the updated keys.

**Handling Rotation (Best Practice):** To ensure zero downtime, RPs should implement a "Lazy Refresh" strategy:

1. **Cache** the JWKS response locally (e.g., for 1 hour).
2. **Check:** When verifying a token, check if the `kid` exists in your cache.
3. **Refresh:** If you receive a token with an unknown `kid`, immediately refresh your cache by calling this endpoint again.
4. **Retry:** Attempt validation again with the newly fetched keys.