Exchange Transaction Signature

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.

Exchange signature API

URLs

Environment	Access Mechanism	URL
Staging	mTLS	https://stg-id.singpass.gov.sg:8443/txn-signatures (Deprecated)
Staging	TLS	https://staging.sign.singpass.gov.sg/api/v1/txn-signatures
Production	mTLS	https://id.singpass.gov.sg:8443/txn-signatures (Deprecated)
Production	TLS	https://app.sign.singpass.gov.sg/api/v1/txn-signatures

Client Authentication

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 Jose Header RFC for more details about what each header presents.

JWT claims

The following claims need to be present.

Path	Type	Description
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

{
  "sign_code": "aRpFkeEbdOSBaeY7aGIk0rkvb90yr9nezLM4cMLOuVc=",
  "iat": 1598238992,
  "sub": "4iHWBHNNrYcXKKMOvk3bIE3CYAQnQ84V"
}

Request

Request headers

Should include the Authorization token descibed in Client Authentication.

Request body

Request body shall be a json object with the sign_code parameter.

{"sign_code":"wOU1mqb7XICjhdTUgl73"}

Example request

POST https://app.sign.singpass.gov.sg/api/v1/txn-signatures HTTP/1.1
Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJhdWQiOiJodHRwczovL2lkLnNpbmdwYXNzLmdvdi5zZy90eG4tc2lnbmF0dXJlcyIsInN1YiI6Im5kaV9yZWdpc3RlcmVkX2NsaWVudF9pZCIsInNpZ25fY29kZSI6IndPVTFtcWI3WElDamhkVFVnbDczIiwiaXNzIjoibmRpX3JlZ2lzdGVyZWRfY2xpZW50X2lkIiwiZXhwIjoxNzM0MzM4Nzc4LCJpYXQiOjE3MzQzMzg3MTh9.1s2vk5I7o1cPYu2Djbf5qVLO4NmruwgI_L2rVqU7Q3q_b_TclSA4ue637OsiCoLTxMC9g5zDDIEjlz3hykBAq4o9jPOhMu4HsBFsiaz9IYmP2OkNnx3kMxBUxeqKZUxz
Content-Type: application/json

{"sign_code":"wOU1mqb7XICjhdTUgl73"}

Response

The response is a JWT signed by Singpass wrapped in a json response.

Example:

{"token":"eyJraWQiOiJuZGlfZHNzX3NpZ25lciIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJhdWQiOiJodHRwczovL2F1ZGllbmNlLm9yaWdpbiIsInN1YiI6IjZlNjc2NjU0LTViYjQtNDIyNy1iYTFhLWYzMDU5ZTIyNWYyMCIsInR4bl9oYXNoX3NpZ25hdHVyZSI6IjZhYzc2MzdkYTkyYzc2Mzg1Zjk1YTkyYzc2MTdlNTkxYThmNmRmOGY3NGYzN2VmOGRiN2UyNWU2NDhlMWRiN2UiLCJ0eG5faGFzaCI6IjZhYzc2MzdkYTkyYzc2Mzg1Zjk1YTkyYzc2MTdlNTkxYThmNmRmOGY3NGYzN2VmOGRiN2UyNWU2NDhlMWRiN2UiLCJpc3MiOiJodHRwczovL2NsaWVudC5yZWRpcmVjdC5vcmlnaW4iLCJleHAiOjE3MzQzMzg4MzUsImlhdCI6MTczNDMzODcxNSwibm9uY2UiOiJjZWJhUTRYaVRoczBvUDA4YXJYY0JRcGordnkraTBCUHRhNFllVFhrTEVFPSJ9.vVZxJrZoUoloLzjvCwB8-Cg0yVxlBRQmGDcGrxNy_Owr8n_NV_sy7oQI0FMzLd4XcGBNfhIdLKBuycQIOZCVWPUU6qrhZFVORfjOCyJc10BvtB3_inOP8drRkHb4Q1o5"}

Token JWT structure

Headers

The following standard JWS headers will be included. Refer to Jose Header RFC for more details about what each header presents.

Header Example

{
  "kid" : "abcd",
  "typ" : "JWT",
  "alg" : "ES256"
}

Claims

The following claims will be returned.

Path	Type	Description
iss (Deprecated)	String	The principal that issued the JWT. https://tools.ietf.org/html/rfc7519#section-4.1.1
sub	String	The user’s Singpass user id signed the transaction. https://tools.ietf.org/html/rfc7519#section-4.1.2
iat	Number	The time at which the JWT was issued. https://tools.ietf.org/html/rfc7519#section-4.1.6
exp	Number	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. https://tools.ietf.org/html/rfc7519#section-4.1.4
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

{
  "sub" : "6e676654-5bb4-4227-ba1a-f3059e225f20",
  "txn_hash_signature" : "6ac7637da92c76385f95a92c7617e591a8f6df8f74f37ef8db7e25e648e1db7e",
  "txn_hash" : "6ac7637da92c76385f95a92c7617e591a8f6df8f74f37ef8db7e25e648e1db7e",
  "exp" : 1734338835,
  "iat" : 1734338715,
  "nonce" : "cebaQ4XiThs0oP08arXcBQpj+vy+i0BPta4YeTXkLEE="
}

Signature

Standard JWT signature, RP MUST validate the signature with Singpass public keys.

Error handling

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.

Http Status	Description
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

Path	Type	Description
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 code representing broad class of error. See Error Codes for the list of possible error codes that can be returned and what they represent.
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

Error Code	Description
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

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "id" : "bcba4bc3-534e-4891-bfa2-e872b4502d80",
  "error" : "CLIENT_SIDE_ERROR",
  "error_description" : "This is an invalid request.",
  "trace_id" : "675fe8742c6442a7c0a1f3d1643ff9af"
}

Fetch our public keys

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 here.

Public keys returned from this endpoint could be in random sequence or rotated for security enhancement.

URLs

Environment	URL
Staging	https://static.staging.sign.singpass.gov.sg/.well-known/keys.json OR https://stg-id.singpass.gov.sg/.well-known/digital-signing-keys (Deprecated)
Production	https://static.app.sign.singpass.gov.sg/.well-known/keys.json OR https://id.singpass.gov.sg/.well-known/digital-signing-keys (Deprecated)

Cache and key rotation

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.