API Documentation

A list of API endpoints supported by sgID.

The API endpoints listed here are for reference purposes only. sgID users are strongly recommended to use the SDK(s) provided which sends these requests for you.

If there are no SDKs provided for your programming language, please refer to Custom Integration on how to set up your own integration.

Endpoints

Do not reuse the example code challenge and code verifier provided in the API examples, as this would expose your API requests to PKCE guessing attacks by malicious users. Refer to the example code under the SDKs section on how to generate valid <code_verifier, code_challenge> pairs.

Create authorization URL

Create an sgID authorization URL to redirect your user to so that they can authenticate with Singpass

GEThttps://api.id.gov.sg/v2/oauth/authorize

Query parameters

Response

A HTML page which contains a sgID QR code if the request is successful, or an error code and error message if there is a problem with the request.

Body

CreateAuthorizationUrlSuccess (string)

Request

const response = await fetch('https://api.id.gov.sg/v2/oauth/authorize', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

"<head>...</head><body>......<body>"

Token exchange

Exchange auth code for access token as part of sgID authorization code flow

POSThttps://api.id.gov.sg/v2/oauth/token

Body

client_id*string

sgID client ID which was provided to you during client registration

client_secret*string

sgID client secret which was provided to you during client registration

code*string

Authorization code that was received from the callback URL after the user authenticates with Singpass

grant_type*string

This field must take the value authorization_code as sgID only supports the OAuth 2.0 authorization code flow

code_verifier*string

A cryptographically random string that was used to generate your code challenge in the authorization request

Response

Successful token exchange

Body

access_tokenstring

Access Token to be used with retrieving the encrypted payload from user info endpoint

id_tokenstring

JWT token with the associated user claims. Encodes the following:

iss (hostname)
sub (end user's unique identifier)
aud (client id)
nonce (only returned if provided in authorization url)
exp (seconds before auth request and access token expires)
iat (timestamp at which id token was issued)

Request

const response = await fetch('https://api.id.gov.sg/v2/oauth/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "client_id": "MYCLIENT-PROD",
      "client_secret": "abcabc[...]abcabc",
      "code": "abcdefg12345678[...]gfedcba",
      "grant_type": "authorization_code",
      "code_verifier": "u1ta-MQ0e7TcpHjgz33M2DcBnOQu~aMGxuiZt0QMD1C"
    }),
});
const data = await response.json();

Response

{
  "access_token": "text",
  "id_token": {
    "access_token": "I6zGnxYTy4fZubtb7LcG48K1fHWb5b",
    "id_token": "eyJhbGciOiJ...[truncated]...L6zm6LaWfkBoA"
  }
}

Request for user info

Exchange access token for user info as part of sgID authorization code flow

GEThttps://api.id.gov.sg/v2/oauth/userinfo

Authorization

Response

Successfully retrieve user info from sgID

Body

substring

End user's unique identifier for your client - This is the same value as the sub claim in the id_token returned from the previous response.

Note that as part of sgID's privacy-preserving measures, each end user's unique identifier is different for each sgID client

keystring

An AES-128-GCM symmetric key, or a block key, that is encrypted with your client's RSA-2048 public key.

dataobject

JSON object which contains the data you requested in your application scope. To prevent sgID from reading the data, the payload is encrypted with the block key referenced in the definition for the key attribute in the same response body.

Refer to our onboarding guide for instructions on decrypting the payload.

Request

const response = await fetch('https://api.id.gov.sg/v2/oauth/userinfo', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "sub": "abcdef",
  "key": "eyJhbGcDpgYRL4chyXTjgim...[truncated]...Gxa2tO7nghnu-ewD5ZqA",
  "data": {
    "myinfo.nric_number": "eyJlbmMiOiJ...[truncated]...QafqHmGERc3A",
    "myinfo.name": "eyJlbmMiOi...[truncated]...UgJ9hDSTNLVw",
    "myinfo.passport_expiry_date": "eyJlbmMiOi...[truncated]...UvS41pKk9VKQ"
  }
}

sgID public keys

GEThttps://api.id.gov.sg/v2/.well-known/jwks.json

Response

A JSON object representing sgID's public keys

Body

keysarray of object

Request

const response = await fetch('https://api.id.gov.sg/v2/.well-known/jwks.json', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "g9DT_3W6OUaKCmjciEM0XNTsz6yTE1bBFec-xiN9zZk",
      "n": "rzz[...]tfbF3Q",
      "e": "AQAB",
      "use": "sig"
    }
  ]
}

sgID OpenID Provider Configuration Document

GEThttps://api.id.gov.sg/v2/.well-known/openid-configuration

Response

A JSON object representing a set of Claims about the sgID's configuration as an OpenID Provider

Body

issuerstring

Issuer of ID Token

authorization_endpointstring

URL of the sgID's OAuth 2.0 Authorization Endpoint

token_endpointstring

URL of the sgID's OAuth 2.0 Token Endpoint

userinfo_endpointstring

URL of the sgID's UserInfo Endpoint

jwks_uristring

URL of the sgID's JSON Web Key Set document

response_types_supportedarray of string

JSON array containing a list of the OAuth 2.0 response_type values that sgID supports

grant_types_supportedarray of string

JSON array containing a list of the OAuth 2.0 Grant Type values that sgID supports

scopes_supportedarray of string

JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that sgID supports

id_token_signing_alg_values_supportedarray of string

JSON array containing a list of the JWS signing algorithms (alg values) supported by sgID for the ID Token to encode the Claims in a JWT

subject_types_supportedarray of string

JSON array containing a list of the Subject Identifier types that sgID supports

code_challenge_methods_supportedarray of string

JSON array containing a list of supported code challenge methods for PKCE

Request

const response = await fetch('https://api.id.gov.sg/v2/.well-known/openid-configuration', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "issuer": "https://api.id.gov.sg/v2",
  "authorization_endpoint": "https://api.id.gov.sg/v2/oauth/authorize",
  "token_endpoint": "https://api.id.gov.sg/v2/oauth/token",
  "userinfo_endpoint": "https://api.id.gov.sg/v2/oauth/userinfo",
  "jwks_uri": "https://api.id.gov.sg/v2/.well-known/jwks.json",
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "scopes_supported": [
    "openid",
    "myinfo.nric_number",
    "myinfo.name"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "subject_types_supported": [
    "pairwise"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ]
}

PreviousCustom Integration NextTroubleshooting

Last updated 11 months ago

{ "issuer": "https://api.id.gov.sg/v2", "authorization_endpoint": "https://api.id.gov.sg/v2/oauth/authorize", "token_endpoint": "https://api.id.gov.sg/v2/oauth/token", "userinfo_endpoint": "https://api.id.gov.sg/v2/oauth/userinfo", "jwks_uri": "https://api.id.gov.sg/v2/.well-known/jwks.json", "response_types_supported": [ "code" ], "grant_types_supported": [ "authorization_code" ], "scopes_supported": [ "openid", "myinfo.nric_number", "myinfo.name" ], "id_token_signing_alg_values_supported": [ "RS256" ], "subject_types_supported": [ "pairwise" ], "code_challenge_methods_supported": [ "S256" ] }