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

# 0. Well-known Endpoints

Corppass supports industry-standard **OpenID Connect (OIDC) Discovery** mechanisms. These publicly accessible endpoints allow Relying Parties (RPs) to programmatically discover Corppass' current configuration, endpoint locations, and cryptographic keys.

By utilizing these endpoints, your application can configure itself dynamically, reducing the risk of hardcoded errors and ensuring resilience against infrastructure changes.

#### Why use these endpoints?

* **Dynamic Configuration:** Automatically updates endpoint URLs if Corppass infrastructure changes.
* **Zero-Downtime Key Rotation:** Automatically fetches new keys when Corppass rotates signatures, preventing service outages.
* **Standard Compliance:** Ensures seamless integration with standard OIDC client libraries.

***

### Integration Workflow

To integrate successfully, your application should implement the following logic to "bootstrap" its configuration at startup and handle key rotation at runtime.

#### Step 1: Fetch Provider Metadata

When: Application Startup

* Initiate a `GET` request to the OpenID Discovery Endpoint.
* This returns a JSON document containing critical configuration data, including the locations of the Authorization, Token, and JWKS endpoints.
* Refer to [OpenID Discovery Endpoint](/docs/singpass-developer-docs/corppass-and-myinfo-business/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/openid-discovery-endpoint.md) for more details.

#### Step 2: Extract & Configure

When: Immediately after Step 1

* Parse the JSON response.
* Configure Endpoints: Update your OIDC client with the dynamic URLs (e.g., for `pushed_authorization_request_endpoint`, `authorization_endpoint`, and `token_endpoint`).
* Locate Keys: Extract the `jwks_uri` field. This URL is required for the next step.

#### Step 3: Fetch & Cache Public Keys

When: Application Startup (and periodically)

* Initiate a `GET` request to the URL found in `jwks_uri`.
* Cache Strategy: Store the retrieved JSON Web Key Set (JWKS) in a local cache (e.g., Redis or memory).
* TTL (Time-To-Live): Set a reasonable expiration (e.g., 1 hour) to balance performance with freshness.
* Refer to [JWKS Endpoint](/docs/singpass-developer-docs/corppass-and-myinfo-business/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/jwks-endpoint.md) for more details.

#### Step 4: Handle Key Rotation (Runtime)

When: Token Verification Fails

* If your application receives a token with a Key ID (`kid`) that is missing from your local cache:
  1. Do not reject immediately.
  2. Force Refresh: Trigger an immediate request to the `jwks_uri` to fetch the latest keys.
  3. Retry Verification: Attempt to verify the token signature again with the updated key set.
  4. Reject: If the key is still missing after the refresh, reject the request.

***

{% content-ref url="/pages/2Ay3oa8jfb21pagacDI0" %}
[OpenID Discovery Endpoint](/docs/singpass-developer-docs/corppass-and-myinfo-business/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/openid-discovery-endpoint.md)
{% endcontent-ref %}

{% content-ref url="/pages/i5LokFxZXN0XExAnafIG" %}
[JWKS Endpoint](/docs/singpass-developer-docs/corppass-and-myinfo-business/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/jwks-endpoint.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.developer.singpass.gov.sg/docs/singpass-developer-docs/corppass-and-myinfo-business/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.