# Embedding Singpass JS

We provide a **core JavaScript library** (Singpass JS) to enable seamless integration with the Singpass Digital Signing Service (DSS). It facilitates transaction signing workflows for Relying Party (RP) applications, covering steps **2.1 to 5.3** in the flow diagram.

**Key Functionalities**

* **Initialisation**: Singpass JS is initialised in the RP’s frontend to set up the transaction signing process.
* **Session Management**: Starts the signing session with transaction details (Step 2.1).
* **QR Code Rendering**: Generates and displays the QR code for the user to scan via SingPass Mobile App (Step 2.2).
* **Status Handling**: Tracks user actions, returning the CHALLENGED status when the QR code is scanned (Step 3.2).
* **Success Confirmation**: Confirms the signed challenge response and returns the success status with the sign code (Step 5.3).

RPs shall embed this Javascript in your front end application. 

## **URLs**

<table><thead><tr><th width="178">Environment</th><th width="576">URL</th></tr></thead><tbody><tr><td>Staging</td><td><p><a href="https://static.staging.sign.singpass.gov.sg/static/ndi_txn_sign.js">https://static.staging.sign.singpass.gov.sg/static/ndi_txn_sign.js</a><br>OR</p><p><a href="https://stg-id.singpass.gov.sg/static/ndi_txn_sign.js">https://stg-id.singpass.gov.sg/static/ndi_txn_sign.js</a> <mark style="color:red;">(Deprecated)</mark></p></td></tr><tr><td>Production</td><td><a href="https://static.app.sign.singpass.gov.sg/static/ndi_txn_sign.js">https://static.app.sign.singpass.gov.sg/static/ndi_txn_sign.js</a><br>OR<br><a href="https://id.singpass.gov.sg/static/ndi_txn_sign.js">https://id.singpass.gov.sg/static/ndi_txn_sign.js</a> <mark style="color:red;">(Deprecated)</mark></td></tr></tbody></table>

{% hint style="warning" %}
You **must provide your frontend origin** during onboarding to allow communication with us.
{% endhint %}

## Content Security Policy (CSP) Requirements <a href="#content_security_policy_csp_requirements" id="content_security_policy_csp_requirements"></a>

This section is important if the RP’s website (where Singpass JS is embedded) uses a Content Security Policy (CSP) header. For Singpass JS to fully function, please ensure that the following CSP attributes are set/added:

* `script-src` [`https://*.singpass.gov.sg`](https://%2A.singpass.gov.sg/)`;`
* `connect-src` [`https://*.singpass.gov.sg`](https://%2A.singpass.gov.sg/)`;`
* `style-src` [`https://*.singpass.gov.sg`](https://%2A.singpass.gov.sg/)`;`
* `img-src` [`https://*.singpass.gov.sg`](https://%2A.singpass.gov.sg/) `data:;`
* `font-src` [`https://fonts.gstatic.com`](https://fonts.gstatic.com/)`;`

Sample CSP header:&#x20;

{% code overflow="wrap" %}

```
content-security-policy: default-src 'self'; script-src 'self' https://*.singpass.gov.sg; connect-src'self' https://*.singpass.gov.sg; style-src 'self' https://*.singpass.gov.sg; img-src 'self' https://*.singpass.gov.sg data:; font-src https://fonts.gstatic.com;
```

{% endcode %}

{% hint style="info" %}
It is not necessary to set/add any CSP attributes if the **RP’s website does not use a CSP header** or has **less strict policies** for all the attributes mentioned above.
{% endhint %}

## UI dimensions <a href="#ui_dimensions" id="ui_dimensions"></a>

The HTML elements will be rendered in a rectangular area with a fixed size with these dimensions, depending on the mode specified via the `additionalOptions` parameter:

| Mode                                 | Dimensions (width by height) |
| ------------------------------------ | ---------------------------- |
| Basic QR with no additional elements | 298px by 367px               |
| QR with download link                | 298px by 416px               |

{% hint style="danger" %}
The RP must allot a minimum space according to these dimensions for the transaction signing UI element to be rendered properly.
{% endhint %}

## UI Reference <a href="#ui_reference" id="ui_reference"></a>

For RP’s reference, this section displays the screens that Singpass JS renders during the transaction signing process. RPs can refer to these screens to get a better idea of how integrating with Singpass JS will look like on their website.

The green border indicates the [`minimum expected size of the DOMElementID`](#ui_dimensions) provided by the RP.

<table><thead><tr><th width="355">Description</th><th>Screen</th></tr></thead><tbody><tr><td>Session initialisation success</td><td><img src="/files/yoGgLDoL9WXBLXZXt7A9" alt=""></td></tr><tr><td>User scanned the QR code using SPM</td><td><img src="/files/7zDxM2oH2Uzh9v6k96lO" alt="" data-size="original"></td></tr><tr><td>Session expired (Before QR code was scanned)</td><td><img src="/files/Ex1EBKZqQgNLjSIoHCyH" alt="" data-size="original"></td></tr><tr><td>Session expired (After QR code was scanned)</td><td><img src="/files/tMlJ8QuXPpwyuN5q3amd" alt="" data-size="original"></td></tr><tr><td>Retryable error occurred <br><br>Users are only allowed to retry up to 1 time. This is to prevent excessive retries on the Singpass server because automated retries are already in place for such API calls.</td><td><img src="/files/8qj8EbaOMKv0H4Bpw1SH" alt="" data-size="original"></td></tr><tr><td><p>Unretryable error occurred<br></p><p>Examples of possible scenarios:</p><ul><li>Error occurred when invoking transactionParamsSupplier </li><li>Pre-flight checks have failed (ie. RP invoked .initTxnSigning() with invalid parameters) </li><li>Retries exhausted Malformed response from Singpass server, which cannot be recovered by retrying </li><li>Client side errors returned from Singpass server </li><li>In the situation where a corresponding erroneous HTTP status code is received, it will be displayed in brackets.</li></ul></td><td><img src="/files/DguYYb2xmBkTUeYtNwkl" alt="" data-size="original"></td></tr><tr><td>Service unavailable. This screen will be displayed if transaction signing service is toggled off on Singpass.</td><td><img src="/files/7OCz6iIEf6QH7IxpzSjM" alt="" data-size="original"></td></tr><tr><td><p>Browser unsupported.<br><br>This screen will be displayed if the end-user’s browser/user-agent is not supported by Singpass JS.</p><p><br>Singpass JS supports recent versions of major browsers, including but not limited to Chrome, Firefox, Edge, Safari, SamsungBrowser and IE 11.</p></td><td><img src="/files/wSWpibuD520IhMbcdluT" alt="" data-size="original"></td></tr><tr><td>Transaction Cancelled. This screen will be displayed if RP invoked .cancelTxnSigningSession()</td><td><img src="/files/YGmxvHpurGiEFbSOWNdj" alt="" data-size="original"></td></tr></tbody></table>


---

# 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.sign.singpass.gov.sg/for-relying-parties/api-documentation/transaction-signing/embedding-singpass-js.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.