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.

PreviousCustom Integration NextTroubleshooting

Last updated 1 year ago

Create authorization URL

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

get

/v2/oauth/authorize

Query parameters

response_typestring · enumrequired

Must be set to code because sgID only supports the authorization code flow

Example: code

Options: code

client_idstringrequired

sgID client ID which was provided to you during client registration

Example: MYCLIENT-PROD

redirect_uristringrequired

The callback URL that was provided during registration. sgID redirects to this URL with the authorization code after the user authenticates with Singpass

Example: https://example.com/callback

scopestringrequired

A URL-encoded string of the scopes your client will request for

Example: openid%20myinfo.name%20myinfo.passport_expiry_date%20myinfo.nric_number

noncestring

Randomly generated string to be returned in the ID token. Used to prevent replay attacks as part of the OpenID Connect 1.0 spec

Example: BQO8SV3ALIYA808IZ8O7PKWRI8A8X6MI

statestring

A unique and non-guessable value associated with each authentication request about to be initiated. Used to prevent CSRF attacks and to maintain state as part of the OAuth 2.0 spec (RECOMMENDED)

Example: tk39drykro3

code_challenge_methodstringrequired

The method used to verify the code challenge. Throws an error response if the value is not 'S256'

Example: S256

code_challengestringrequired

A SHA256 hashed string that should be used to verify against the code verifier in the token request

Example: CUZX5qE8Wvye6kS_SasIsa8MMxacJftmWdsIA_iKp3I

Responses

text/html

text/plain

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.id.gov.sg/v2/oauth/authorize?response_type=code&client_id=MYCLIENT-PROD&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%2520myinfo.name%2520myinfo.passport_expiry_date%2520myinfo.nric_number&code_challenge_method=S256&code_challenge=CUZX5qE8Wvye6kS_SasIsa8MMxacJftmWdsIA_iKp3I'

200

500

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

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.

Token exchange

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

post

/v2/oauth/token

Body

client_idstringrequired

sgID client ID which was provided to you during client registration

client_secretstringrequired

sgID client secret which was provided to you during client registration

codestringrequired

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

grant_typestringrequired

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

code_verifierstringrequired

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.id.gov.sg/v2/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{"client_id":"MYCLIENT-PROD","client_secret":"abcabc[...]abcabc","code":"abcdefg12345678[...]gfedcba","grant_type":"authorization_code","code_verifier":"u1ta-MQ0e7TcpHjgz33M2DcBnOQu~aMGxuiZt0QMD1C"}'

200

400

401

500

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

Successful token exchange

Request for user info

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

get

/v2/oauth/userinfo

Authorizations

Responses

application/json

text/plain

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.id.gov.sg/v2/oauth/userinfo' \
  --header 'Authorization: Bearer JWT'

200

401

500

{
  "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"
  }
}

Successfully retrieve user info from sgID

sgID public keys

get

/v2/.well-known/jwks.json

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.id.gov.sg/v2/.well-known/jwks.json'

200

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

A JSON object representing sgID's public keys

sgID OpenID Provider Configuration Document

get

/v2/.well-known/openid-configuration

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.id.gov.sg/v2/.well-known/openid-configuration'

200

{
  "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"
  ]
}

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