Exchange Transaction Signature
Last updated
Was this helpful?
Last updated
Was this helpful?
This section describes the process where the Relying Party (RP) backend exchanges the sign code received from the Singpass for the user's digital signature. This step finalises the transaction signing workflow, ensuring the transaction is securely signed and validated.
Staging
mTLS
https://stg-id.singpass.gov.sg:8443/txn-signatures (Deprecated)
Staging
TLS
Production
mTLS
https://id.singpass.gov.sg:8443/txn-signatures (Deprecated)
Production
TLS
RPs are required to authenticate themselves by specifying a signed JWT via the Authorization header.
JWT header
The following standard JWS headers need to be included. Refer to for more details about what each header presents.
JWT claims
The following claims need to be present.
sub
String
The Client ID generated during transaction signing replying party registration.
sign_code
String
The Singpass generated code that was returned to the RP via the RP’s redirect URI (specified in the sign_code query parameter).
iat
Number
The time at which the JWT was issued.
Claims example
Request headers
Request body
Request body shall be a json object with the sign_code parameter.
Example request
The response is a JWT signed by Singpass wrapped in a json response.
Example:
Headers
Header Example
Claims
The following claims will be returned.
iss
(Deprecated)
String
sub
String
iat
Number
exp
Number
nonce
String
The value passed by the signing partner during the init session API call
txn_hash_signature
String
The hex-encoded user signature over the txn_hash
txn_hash
String
The SHA-256 hash of the txn_id and txn_instructions field calculated in this manner: sha256(<txn_id>:<txn_instructions>). Encoded in hexadecimal.
Claims Example
Signature
Singpass APIs are RESTful in design and communicate classes of errors based on the Http Status code. The status code should be used to determine if the error is caused by consumer or provider. Consumers should log the HTTP status code along with the id and/or trace_id of the error.
4xx
Errors caused by API consumer. You can expect codes such as 400, 401, 403, 404 etc if incorrect requests are made to APIs.
Example: 400: Invalid/missing request arguments
5xx
Errors caused by API provider or its dependencies. You can expect codes such as 500, 502, 503 etc if there is an issue on Singpass or its dependencies.
Example: 500: Internal Server Error due to some kind of programming error.
Error response json
id
String
The unique identifier for this error/request. Please log this identifier for support and debugging purposes.
trace_id
String
(Optional) An auxiliary id for request correlation across services. Please also log this identifier for operational support and debugging purposes.
error
String
error_description
String
Returns human readable general information about the reason for the error. Note that due to security reasons; detailed information is unlikely to be available in this message.
Error codes
CLIENT_SIDE_ERROR
Generic error code for an invalid request.
SERVER_SIDE_ERROR
Generic error code for an error that occurred in Singpass.
UNAUTHORIZED
Authorisation header value is invalid.
ARGUMENTS_NOT_VALID
Some request parameters are invalid.
Example: Invalid Request Parameters
Public keys returned from this endpoint could be in random sequence or rotated for security enhancement.
Staging
Production
For varying reasons, keys used for signing can and will be rotated/changed with no defined schedule, and at the full discretion of Singpass. When a key rotation happens, the new key will be available from the JWKS endpoint and will have a different kid value. The new kid value will be reflected in all the new JWTs signed by Singpass. In such cases, cached copies of Singpass public keys must be refreshed by re-invoking the JWKS endpoint.
If the validation of the Singpass signature fails, re-fetch from the JWKS endpoint once for that validation.
Please read through the list of DON’Ts below:
Do not assume the position of a signing key among the list of the returned keys.
Do not validate Singpass signatures using a hardcoded public key OR kid. Always determine the correct key (for signature verification) by inspecting the kid from the JWS header, and use it to retrieve the public key from our JWKS endpoint.
Do not cache only 1 key. Caching should be done for the entire JWKS.
Should include the Authorization token descibed in .
The following standard JWS headers will be included. Refer to for more details about what each header presents.
The principal that issued the JWT.
The user’s Singpass user id signed the transaction.
The time at which the JWT was issued.
The expiration time on or after which the JWT MUST NOT be accepted by Singpass for processing. Additionally, Singpass will not accept tokens with an exp longer than 2 minutes since iat.
Standard JWT signature, RP MUST validate the signature with
Error code representing broad class of error. See for the list of possible error codes that can be returned and what they represent.
Integrating parties can verify the signature of a JWT from Singpass by acquiring the signing public key from this endpoint. More information about a JSON Web Key (JWK) endpoint can be found .
OR
(Deprecated)
OR (Deprecated)