# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/jwks-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.