SGDex API (1.2.2-release)

This section gives an introduction to SGDex.

SGDex (Singapore Data Exchange) is a data exchange layer platform that supports multiple data exchanges.

SGDex is organised around REST and returns JSON-encoded responses with standard HTTP response codes.

SGDex API gateway supports accessing of APIs via HTTP over TLS (Transport Layer Security) version 1.2 standards.

Supported Cipher Suites

The list of supported Cipher Suites are as follows:

• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Data Exchange clients (e.g. SGTraDex) must authenticate to SGDex for every request. SGDex uses JWT (specified in RFC 7523) provided in the Authorization header as a bearer token (specified in RFC 6750) for client authentication.

JWT format

Briefly, an unencrypted, signed JWT consists of three parts:

1. The header;
2. The body or payload; and
3. A signature of the payload.

The header may include information about the key and algorithm used to sign the payload. This is needed unless the receiver has obtained this information through other means. As an example, a JWT used for client authentication may have a header and payload like this:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "7229075d-972f-4b21-8a0c-38db3a7f2a98"
}

The associated payload may look like this:

{
  "aud": "https://api.sgdex.gov.sg",
  "iss": "client-one",
  "sub": "client-one",
  "nbf": 1535806905,
  "exp": 1535810505,
  "iat": 1535806905,
  "jti": "id123456"
}

JWT parameters include the following:

Signature

• A JWT must be digitally signed using a private key in asymmetric cryptography (e.g. RS256).
• A client using the authentication method has to register its public key to SGDex in advance so that the SGDex can verify the token.

Sending JWT in Request

The JWT sent to the SGDex should be a Bearer token in the Authorization header, as described in RFC 6750. A sample request is shown below:

GET /{dex}/{usecase}/{api} HTTP/1.1
Host: stg.api.sgdex.gov.sg
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL3N0Zy5hcGkuc2dkZXguZ292LnNnIiwiaXNzIjoiY2xpZW50LW9uZSIsInN1YiI6ImNsaWVudC1vbmUiLCJuYmYiOjE1MzU4MDY5MDUsImV4cCI6MTUzNTgxMDUwNSwiaWF0IjoxNTM1ODA2OTA1LCJqdGkiOiJpZDEyMzQ1NiJ9.1ba2xgaRfxiu18SBPauA4ibe21uqI1lymtFoYXrFpMysQVADei98guL4QKHqgwD6UwHBOkC_L5W6TR19g1fuoQ

The Partner's application is required to generate client assertions to be attached to server-to-server calls to prove authenticity (Refer to https://datatracker.ietf.org/doc/html/rfc7521). The partner's private key signs the assertion metadata, and SGDex will use the partner's onboarded JWKS endpoint to obtain the public key for verification. Below is a sample of the JWT header and payload of the client assertion:

  {
    "typ": "JWT",
    "alg": "ES256",
    "kid": "x0zDLIC9yNRIXu3gW8nTQDOMNe7sKMAjQnZj3AWTW2U",
  } . {
    "sub": "STG2-APIM-SELF-TEST",
    "jti": "jNDZuyLw66gkTjmCNMawzrTJNlhS8wdjpU0DHTzo",
    "aud": "https://api.staging-sgdex.gov.sg/sgfindex/fpdata/77e0ff15-88be-474a-84ab-5b24ac2fb9d6",
    "iss": "STG2-APIM-SELF-TEST",
    "iat": 1662365106,
    "exp": 1662365406,
    "htm": "POST"
  }

Description of JWT header attributes:

• {typ} Type - value "JWT"
• {alg} Algorithm - value "ES256"
• {kid} Key ID - The unique identifier for the key.

Description of JWT payload attributes:

• {sub} Subject - client_id issued by SGDex upon onboarding
• {jti} JWT ID - random unique identifier
• {aud} Audience - URL that partner's application is calling
• {iss} Issuer - client_id issued by SGDex upon onboarding
• {iat} Issued At (Payload) - current timestamp
• {exp} Expiry (Payload) - expiry timestamp
• {htm} HTTP Method (Payload) - HTTP method for the request to which the JWT is attached

When onboarding to SGDex, every Participant is required to provide JWKS (JSON Web Key Set) endpoint.

The JWKS endpoint which hosts the JWK (JSON Web Key) must meet the following requirements.

• Endpoint is served behind HTTPS on port 443 using a TLS server certificate issued by a standard publicly verifiable CA issuer (no private CAs), with a complete certificate chain presented by the server.
• No other custom HTTP header requirements outside standard HTTP headers.
• Able to respond in 3 seconds.

A JWKS endpoint can host multiple JWKs, using a key ID kid to distinguish between each JWK.

The JWK will be used in the following scenarios:

• Signature JWK is used to verify the client assertion presented when consuming APIs.
• Encryption JWK is used to encrypt the response of data APIs.

JWK for Signature

The signature JWK will be used to verify the client assertion JWT presented in request, thereby authenticating the client.

The signature JWK should have the following attributes:

• Must contain a key use use field of value sig, refer to rfc7517#section-4.2.

• Must contain a key ID kid field, refer to rfc7517#section-4.5.

• Must contain key type kty of either EC or RSA.

  • For key type kty of value EC, with algorithm alg of value ES256 and curve crv of value P-256.

  • For key type kty of value RSA, with algorithm alg of value RS256.

Example:

// EC Signature Key
{
  "kty": "EC",
  "use": "sig",
  "kid": "sig-2021-01-15T12:09:06Z",
  "alg": "ES256",
  "crv": "P-256",
  "x": "Tjm2thouQXSUJSrKDyMfVGe6ZQRWqCr0UgeSbNKiNi8",
  "y": "8BuGGu519a5xczbArHq1_iVJjGGBSlV5m_FGBJmiFtE"
}

// RSA Signature Key
{
  "kty": "RSA",
  "kid": "sig-2023-06-15T14:31:42Z",
  "use": "sig",
  "alg": "RS256",
  "e": "AQAB",
  "n": "z7HAG7BFZu-VkvcMceXFH4Jt0y2ZZTgD10Y_GuD8iXi_c6SeAreF6KEXpq3mC_bpspf75hCW--mibqiXxJhxOAAOfQ0WAU-W2tWWlv--tDKsLlKUFF5ebWyZHjWPqPEjRIyc8nkqvlGqAjLp7oefcpOgvbZwMcSc7hrh7NX2nSBDJzyBCVRx-CLKe5q3_9bZzbfudK2RHo9o9p6pC6QCE6url2fEpsPC4M3j4T283ksJFpqOxsbmwp5ns_tmHBkN099NHfgrcda5GLrv8DYKW1vcPQ1RlDThlP3EiWefXx76AiTMby1CkArwafD20zurqdngcSjHuJ80_hxou1WCfw"
}

Key rotation for signature key

To rotate the signature keys with zero downtime, the client must:

• Host the replacement signature key in the JWKS endpoint onboarded.
• Ensure the replacement signature key has a different key ID kid to the original key.
• Ensure the replacement signature key matches the other cryptographic key requirements.

JWK for Encryption

The encryption JWK will be used to encrypt data requested.

The encryption JWK must have the following attributes:

• Must contain a key use use field of value enc, refer to rfc7517#section-4.2.

• Must contain a key ID kid field, refer to rfc7517#section-4.5.

• Must contain key type kty of either EC or RSA.

  • For key type kty of value EC, with algorithm alg of value ECDH-ES+A256KW and curve crv of value P-256.

  • For key type kty of value RSA, with algorithm alg of value RSA-OAEP.

• If there are multiple keys that meets requirements, the first EC or RSA key will be used.

• If encryptionKid is provided as parameter during data pull, encryptionKid will be used to filter the keys in the JWKS. Criteria of keys listed above applies.

Example:

// EC Encryption Key
{
  "kty": "EC",
  "use": "enc",
  "kid": "enc-2021-01-15T12:09:06Z",
  "crv": "P-256",
  "x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY",
  "y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE",
  "alg": "ECDH-ES+A256KW"
}

// RSA Encryption Key
{
  "kty": "RSA",
  "kid": "enc-2023-06-15T14:31:42Z",
  "use": "enc",
  "alg": "RSA-OAEP",
  "e": "AQAB",
  "n": "-fbCIK-zGdvVjoOJ78M-7l-Avu80MsSPvOCn1IKUACRS31G-H2Z64vvjz6o-h5dEldwhpFCRPmdTl0TEvj4AIcw6CcWLUmL7QttLSW_kaZ3FVV_UaUzjGSP5G9MrEfC67zwl7b1td3N93szrPA47YYXjgmLq9t2MswFyIYQ6pkBhO4_9joTmrz9LcPnOQrqZx2_X9GUIsQAA52Su3ZdxCuCLhUdSe9_AwMdxuhtBCfTdwJEArwcj-3jDxAlZL_Vr1OImBtsgQ2dnCMDE_weaA2NQp2dIQ5zj7a_zaZ8l3G5L2TGKXeCEo8rDuGjvuYQ4fLxjyiJqLydzosCaeB7N7w"
}

Key rotation for encryption key

To rotate the encryption key with zero downtime, the client must:

• Host the replacement encryption key in the JWKS endpoint onboarded.
• Identify private key to decrypt JWE using key ID kid in JWE.
• Ensure the replacement encryption key matches the other cryptographic key requirements.

Before user data is returned to a Consumer, the response payload for the Person/Corporate Data API is first signed, then encrypted by SGDex:

• Signing is done using JWS (JSON Web Signature) format
• Encryption is done using JWE (JSON Web Encryption) Compact Serialization format

In order to read the response payload, a Consumer has to perform the following steps in this order:

1. Decrypt the response payload with the Consumer's private encryption key. This private encryption key should correspond to the Consumer's encryption public key in the Consumer's JWKS endpoint that has been onboarded onto SGDex.
2. Validate the decrypted payload signature with SGDex's public signing key returned from SGDex's JWKS endpoint.

After completing the steps above, the Consumer will be able to extract the payload in JSON format.

Step 1: Decryption

• The response payload is encrypted using a Consumer public encryption key provided in their onboarded JWKS endpoint. Therefore, decryption of the payload is to be done using the Consumer's corresponding private encryption key.
• Current encryption algorithms used:
  • ECDH-ES+A256KW (for content key wrapping)
  • A256GCM (for content encryption)

Step 2: Verification of Signature

• The decrypted payload is signed according to the JWS (JSON Web Signature) format, similar to the access token.
  • Signature algorithm used is ES256.
  • Additional attributes iat (epoch time when the signature is generated) is included in the JWS header.
  • Verify the decrypted payload signature with SGDex's public signing key returned from SGDex's JWKS endpoint.

SGDex uses standard HTTP response codes to indicate the success or failure of each API request. For successful requests, our APIs return 2XX codes. Generally, our HTTP error codes have the following implication:

• 4XX: Indicates error in the request format, parameters or that your requested items are not found
• 5XX: Indicates Server errors

The general format of our error responses are as follows:

{
    "code": "integer (int32), this is our custom error code.",
    "message": "string"
}

List of HTTP Response Codes:

Refer to the individual API definitions for the error codes you might encounter for each API.

Staging Environment

This environment allows you to test your application with production-level security requirements, without needing to test your application directly in production.

The following are some essential information that you might need to test your applications with:

• Domain Name: https://api.staging-sgdex.gov.sg/

Production Environment

The environment where your application will be integrated with SGDex in production.

The following are some essential information that you might need to test your applications with:

• Domain Name: https://api.sgdex.gov.sg/

This section mentions all information related to versioning.

• 1.2.2-release (10 Jun 2025)

  • Added person and entity API
  • Added person and entity scopes

• 1.2.1-release (24 Jul 2024)

  • Cleaning up of specifications

• 1.2.0-release (27 Jun 2024)

  • Removed organisation concept
  • Removed dex path parameter from application, endpoint, jwks endpoint, webhook. organisation and participant API.
  • Updated update enrolment API to support the update of processing_task array
  • Added create authorisation request API

• 1.1.0-release (6 Nov 2023)

  • Removed usecase api service concept
  • Removed directory concept
  • API/Topic softlink to usecase only
  • Mandate iat field as mandatory in generated signed JWT
  • Added new resource api
  • Added new supported security mechanism (APIkey) for endpoint

• 1.0.0-release (20 Jun 2022)

  • Added new scope field to routing api - Retrieving Data
  • Added input format and validation pattern

• 0.1.1 (13 Jan 2022)

  • Added SGTraDex helper API, JWKS API

• 0.1.0 (12 August 2021)

  • Initial Draft including APIs for pull and push data

Releases

SGDex's RESTful API adopts Semantic Versioning 2.0.0 for releases with the following format:

The table below lists the possible changes to the release version numbers and what they imply.

The following are the available scopes for SGDex Person & Entity APIs.

Please contact the SGDex team at support@sgdex.gov.sg for support.