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

get

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

Query parameters

response_typestring · enumRequired

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

Example: codePossible values:

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

noncestringOptional

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

statestringOptional

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

200

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.

text/html

stringOptionalExample: <head>...</head><body>......<body>

500

Server error

text/plain

get

/v2/oauth/authorize

GET /v2/oauth/authorize?response_type=code&client_id=MYCLIENT-PROD&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20myinfo.name%20myinfo.passport_expiry_date%20myinfo.nric_number&code_challenge_method=S256&code_challenge=CUZX5qE8Wvye6kS_SasIsa8MMxacJftmWdsIA_iKp3I HTTP/1.1
Host: api.id.gov.sg
Accept: */*

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

Token exchange

post

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

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

200

Successful token exchange

application/json

access_tokenstringOptional

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

id_tokenstringOptional

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)

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

400

Invalid request due to one of the following errors:

Invalid grant type
Missing parameters in the request body (client_id, client_secret, redirect_uri, or code)
Invalid grant (auth code is expired or invalid, or redirect_uri does not match

application/json

401

Invalid client credentials

application/json

500

Server error

application/json

post

/v2/oauth/token

POST /v2/oauth/token HTTP/1.1
Host: api.id.gov.sg
Content-Type: application/json
Accept: */*
Content-Length: 198

{
  "client_id": "MYCLIENT-PROD",
  "client_secret": "abcabc[...]abcabc",
  "code": "abcdefg12345678[...]gfedcba",
  "grant_type": "authorization_code",
  "code_verifier": "u1ta-MQ0e7TcpHjgz33M2DcBnOQu~aMGxuiZt0QMD1C"
}

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

Request for user info

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successfully retrieve user info from sgID

application/json

substringOptional

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

keystringOptional

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

dataobjectOptional

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.

401

Missing or invalid bearer token

text/plain

500

Server error

text/plain

get

/v2/oauth/userinfo

GET /v2/oauth/userinfo HTTP/1.1
Host: api.id.gov.sg
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

get

Responses

200

A JSON object representing sgID's public keys

application/json

A JWK container object which contains an array of JWK Key Objects. See the IETF document for JSON Web Key (JWK) for more details.

keysobject[]Optional

Each of the items in the array is a JWK Key Object

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

get

/v2/.well-known/jwks.json

GET /v2/.well-known/jwks.json HTTP/1.1
Host: api.id.gov.sg
Accept: */*

200

A JSON object representing sgID's public keys

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

sgID OpenID Provider Configuration Document

get

Responses

200

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

application/json

A JSON object representing a set of Claims about the sgID's configuration as an OpenID Provider. See RFC 7033 for more details

issuerstringOptional

Issuer of ID Token

Example: https://api.id.gov.sg/v2

authorization_endpointstringOptional

URL of the sgID's OAuth 2.0 Authorization Endpoint

Example: https://api.id.gov.sg/v2/oauth/authorize

token_endpointstringOptional

URL of the sgID's OAuth 2.0 Token Endpoint

Example: https://api.id.gov.sg/v2/oauth/token

userinfo_endpointstringOptional

URL of the sgID's UserInfo Endpoint

Example: https://api.id.gov.sg/v2/oauth/userinfo

jwks_uristringOptional

URL of the sgID's JSON Web Key Set document

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

response_types_supportedstring[]Optional

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

Example: ["code"]

grant_types_supportedstring[]Optional

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

Example: ["authorization_code"]

scopes_supportedstring[]Optional

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

Example: ["openid","myinfo.nric_number","myinfo.name"]

id_token_signing_alg_values_supportedstring[]Optional

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

Example: ["RS256"]

subject_types_supportedstring[]Optional

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

Example: ["pairwise"]

code_challenge_methods_supportedstring[]Optional

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

Example: ["S256"]

get

/v2/.well-known/openid-configuration

GET /v2/.well-known/openid-configuration HTTP/1.1
Host: api.id.gov.sg
Accept: */*

200

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

{
  "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 2 years ago

Was this helpful?

hashtagEndpoints

hashtagCreate authorization URL

hashtagToken exchange

hashtagRequest for user info

hashtagsgID public keys

hashtagsgID OpenID Provider Configuration Document

Endpoints

Create authorization URL

Token exchange

Request for user info

sgID public keys

sgID OpenID Provider Configuration Document