> 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/technical-concepts/client-assertion-jwt.md).

# Client Assertion JWT

Corppass supports **JWT-based client authentication** using the mechanism defined in [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523). Clients must generate and sign a JWT — known as a **client assertion** — and present it to Corppass when authenticating at the [PAR](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/2.-authorization-endpoint.md) or [Token](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/3.-token-endpoint.md) endpoints.

This method is especially suitable for **confidential clients** that can securely manage private keys.

### When to Use

A client assertion JWT must be used whenever the client authenticates with Corppass, including during:

* [Pushed authorization requests](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/1.-pushed-authorization-request-par-endpoint.md)
* [Token requests](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/3.-token-endpoint.md)

The JWT is passed as two fields:

```markup
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<signed-JWT>
```

{% hint style="warning" %}
Corppass **strongly recommends** clients to use **libraries** to handle JWTs instead of attempting it themselves.&#x20;

See [here](https://www.jwt.io/libraries) for an overview of JWT libraries that clients can use to do so.
{% endhint %}

## JWT Structure

A signed client assertion JWT follows the typical JWS format:

```markup
<base64url-encoded header>.<base64url-encoded payload>.<base64url-encoded signature>
```

### JWT Header Example

```json
{
    "typ" : "JWT",
    "alg" : "ES256",
    "kid": "d591e152-886e-46cc-aa70-36a4431162a6"
}
```

<table><thead><tr><th width="217">Field</th><th>Description</th></tr></thead><tbody><tr><td>typ</td><td>The type of the token, typically set to <code>"JWT"</code>.</td></tr><tr><td>alg</td><td>The algorithm used for signing the JWT. Supported values are <code>ES256</code>, <code>ES256K</code>, <code>ES384</code>, and <code>ES512</code>.</td></tr><tr><td>kid</td><td>The Key ID associated with the signing key, matching the JWK provided during onboarding.</td></tr></tbody></table>

### JWT Claims (Payload) Example

```json
{
  "iss": "your-client-id",
  "sub": "your-client-id",
  "aud": "https://id.corppass.gov.sg/token",
  "jti": "random-uuid-12345",
  "exp": 1712486400,
  "iat": 1712486100
}
```

<table><thead><tr><th width="132.19140625">Claims</th><th width="117.03515625">Required</th><th>Description</th></tr></thead><tbody><tr><td>iss</td><td>Yes</td><td>The client ID of the registered client.</td></tr><tr><td>sub</td><td>Yes</td><td>The client ID of the registered client.</td></tr><tr><td>aud</td><td>Yes</td><td>The intended audience for this JWT. Must match the <code>issuer</code> field (<code>iss</code>) from the OpenID Discovery endpoint.</td></tr><tr><td>jti</td><td>Yes</td><td><p>The unique identifier for the JWT.</p><p>Prevents replay attacks. Must be unique for each JWT.</p></td></tr><tr><td>iat</td><td>Yes</td><td>Issued-at time (epoch timestamp).</td></tr><tr><td>exp</td><td>Yes</td><td>The expiration time after which the JWT is no longer valid.</td></tr></tbody></table>

{% hint style="warning" %}

## **Token Maximum Lifetime Requirement**

Corppass will **reject** client assertion JWTs if the **maximum token lifespan** is more than **2 minutes.** This means that the `exp` claim must be **within 2 minutes or less** than the `iat`.&#x20;

This follows the best practices outlined in [Section 3 of RFC 7523](https://www.rfc-editor.org/rfc/rfc7523#section-3). RPs should ensure tokens are short-lived and avoid excessive clock skew.&#x20;
{% endhint %}


---

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

```
GET https://docs.corppass.gov.sg/technical-specifications/technical-concepts/client-assertion-jwt.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.