API Documentation

Developer Docs

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

ResponsestringExample: <head>...</head><body>......<body>

500

Server error

text/plain

get

GET /v2/oauth/authorize HTTP/1.1
Host: api.id.gov.sg
Accept: */*

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

Request for user info

get

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

Authorizations

Responses

200

Successfully retrieve user info from sgID

application/json

401

Missing or invalid bearer token

text/plain

500

Server error

text/plain

get

GET /v2/oauth/userinfo HTTP/1.1
Host: api.id.gov.sg
Authorization: Bearer JWT
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

get

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

get

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

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

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

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

Endpoints

Endpoints

Create authorization URL

Request for user info

sgID public keys

sgID OpenID Provider Configuration Document

Token exchange