> This page is for version 0.0.75.
> For other versions, use one of these documentation indexes:
> - 0.0.79 (default): https://docs.refer.health.gov.sg/0-0-79/llms.txt
> - 0.0.78: https://docs.refer.health.gov.sg/0-0-78/llms.txt
> - 0.0.77: https://docs.refer.health.gov.sg/0-0-77/llms.txt
> - 0.0.76: https://docs.refer.health.gov.sg/0-0-76/llms.txt
> - 0.0.75: https://docs.refer.health.gov.sg/0-0-75/llms.txt
> - 0.0.74: https://docs.refer.health.gov.sg/0-0-74/llms.txt
> - 0.0.73: https://docs.refer.health.gov.sg/0-0-73/llms.txt
> - 0.0.72: https://docs.refer.health.gov.sg/0-0-72/llms.txt
> - 0.0.71: https://docs.refer.health.gov.sg/0-0-71/llms.txt
> - 0.0.70: https://docs.refer.health.gov.sg/0-0-70/llms.txt
> - 0.0.69: https://docs.refer.health.gov.sg/0-0-69/llms.txt
> - 0.0.68: https://docs.refer.health.gov.sg/0-0-68/llms.txt
> - 0.0.67: https://docs.refer.health.gov.sg/0-0-67/llms.txt
> - 0.0.66: https://docs.refer.health.gov.sg/0-0-66/llms.txt
> - 0.0.65: https://docs.refer.health.gov.sg/0-0-65/llms.txt
> - 0.0.64: https://docs.refer.health.gov.sg/0-0-64/llms.txt
> - 0.0.63: https://docs.refer.health.gov.sg/0-0-63/llms.txt
> - 0.0.62: https://docs.refer.health.gov.sg/0-0-62/llms.txt
> - 0.0.61: https://docs.refer.health.gov.sg/0-0-61/llms.txt
> - 0.0.60: https://docs.refer.health.gov.sg/0-0-60/llms.txt
> - 0.0.59: https://docs.refer.health.gov.sg/0-0-59/llms.txt
> - 0.0.58: https://docs.refer.health.gov.sg/0-0-58/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.refer.health.gov.sg/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.refer.health.gov.sg/_mcp/server.

All API requests must be authenticated using a **JWT (JSON Web Token)** signed with the private key we provide for your API key.

Each client is issued:

* **An API key name** — this identifies your integration.
* **An ES256 private key** — used to sign JWTs.
* **One or more `system` values** — depending on which systems your API key is authorized to act on.

Your service should generate a short-lived JWT in the `Authorization` header of every request:

```json
Authorization: Bearer <jwt>
```

Requests without a valid JWT will be rejected with `401 Unauthorized`.

### JWT Requirements

The JWT must satisfy all of the following:

**Signing Algorithm**

* Must be signed using **ES256**
* Must be signed using the **private key** associated with your API key.

  The server will use the stored public key to verify signatures.

**Headers**

| Header | Type   | Required | Description       |
| ------ | ------ | -------- | ----------------- |
| `alg`  | string | Yes      | Must be `"ES256"` |
| `typ`  | string | Yes      | `"JWT"`           |

**Claims**

| Claim | Required | Type   | Description                                                                                                                                          |
| ----- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss` | Yes      | string | The **API key name** we provided to you.                                                                                                             |
| `sub` | Optional | string | Specifies which `system` you are acting on behalf of (see below). If your API key is associated with **only one system**, you should **omit** `sub`. |
| `iat` | Yes      | number | Issued-at timestamp (UNIX seconds).                                                                                                                  |
| `exp` | Yes      | number | Expiry timestamp (UNIX seconds). Max validity: **15 seconds**.                                                                                       |

### When to include `sub`

If your API key is associated with **multiple systems**, you can explicitly set:

```
sub: "<system>"
```

If your API key is associated with **only one system**, you should **omit** `sub`. In that case, the server will automatically assign the only system linked to your API key.

### Examples

Here is a code snippet in `Typescript`. Alternatively, you can use our [client SDK](https://www.npmjs.com/package/@opengovsg/refx-ts-sdk?activeTab=versions) which handles signing JWT token.

```tsx
import jwt from "jsonwebtoken"

interface GenerateJwtOptions {
  iss: string             // API key name
  sub?: string            // Optional subject
}

export function generateJwt(privateKey: string, { iss, sub }: GenerateJwtOptions): string {
  const now = Math.floor(Date.now() / 1000);

  const payload = {
    iss,
    iat: now,
    exp: now + 15
  }

  if (sub) {
    payload.sub = sub;
  }

  return jwt.sign(payload, privateKey, {
    algorithm: "ES256"
  })
}
```