API Reference

This page contains comprehensive API documentation for the TypeScript / JavaScript SDK. If you're looking to get started quickly, visit our quick start or our framework-specific guides.

The source code can be found on GitHub.

convertPkcs1ToPkcs8

convertPkcs1ToPkcs8(pkcs1: string): string

Converts a private key in PKCS1 format to PKCS8.

Parameters

<string> Private key as a string.

Returns

<string> Private key in PKCS8 format.

generateCodeChallenge

generateCodeChallenge(codeVerifier: string): string

Calculates the S256 code challenge for a provided code verifier.

Parameters

<string> The code verifier.

Returns

<string> The calculated code challenge.

generateCodeVerifier

generateCodeVerifier(length: number = 43): string

Generates the random code verifier.

Parameters

<number> (Optional) The length of the code verifier to generate. Defaults to 43.

Throws

Error if length is < 43 or > 128.

Returns

<string> The generated code verifier.

generatePkcePair

generatePkcePair(length: number = 43): {
    codeVerifier: string;
    codeChallenge: string;
}

Generates a challenge pair where code_challenge is the generated S256 hash from code_verifier.

Parameters

<number> (Optional) The length of the code verifier. Defaults to 43.

Throws

Error if length is < 43 or > 128.

Returns

<Object>

• codeChallenge: <string> S256 code challenge generated from the code verifier.

• codeVerifier: <string>

SgidClient

Class which allows you to interact with the sgID API.

constructor

SgidClient({
    clientId,
    clientSecret,
    privateKey,
    redirectUri,
    hostname = "https://api.id.gov.sg",
}: {
    clientId: string;
    clientSecret: string;
    privateKey: string;
    redirectUri?: string;
    hostname?: string;
}): SgidClient

Initialises an SgidClient instance.

Parameters

<Object>

• clientId: <string> Client ID provided during client registration.

• clientSecret: <string> Client secret provided during client registration.

• privateKey: <string> Client private key provided during client registration.

• redirectUri: <string> (Optional) Redirection URI for user to return to your application after login. If not provided in the constructor, this must be provided to the authorization_url and callback functions.

• hostname: <string> (Optional) Hostname of OpenID provider (sgID). Defaults to "https://api.id.gov.sg".

authorizationUrl

authorizationUrl({
    state,
    scope = "openid myinfo.name",
    nonce = generators.nonce(),
    redirectUri = this.getFirstRedirectUri(),
    codeChallenge
}: {
    state?: string;
    scope?: string | string[];
    nonce?: string | null;
    redirectUri?: string;
    codeChallenge: string;
}): {
    url: string;
    nonce?: string;
}

Generates authorization url to redirect end-user to sgID login page.

Parameters

<Object>

• state: <string> (Optional) A string which will be passed back to your application once the end-user logs in. You can also use this to track per-request state.

• scope: <string> | <string[]> (Optional) Scopes being requested. Can be provided as a string array or a space-concatenated string. "openid" must be provided as a scope. Defaults to "openid myinfo.name".

• nonce: <string> | <null> (Optional) Random, unique value to associate a user-session with an ID Token and to mitigate replay attacks. Set as null to omit the nonce. Defaults to a randomly generated nonce if unspecified or set as undefined.

• redirectUri: <string> (Optional) The redirect URI used in the authorization request. If this param is provided, it will be used instead of the redirect URI provided in the SgidClient constructor. If not provided in the constructor, the redirect URI must be provided here. Defaults to the redirectUri provided in the constructor.

• codeChallenge: <string> The code challenge generated from generatePkcePair().

Throws

Error if redirect URI is provided in neither the constructor nor this function.

Returns

<Object>

• url: <string> Generated authorization url.

• nonce: <string> | <undefined> Provided nonce, randomly generated nonce, or undefined (based on nonce input). Should be stored in the user's session so it can be retrieved later for use in callback.

callback

async callback({
    code,
    nonce,
    redirectUri = this.getFirstRedirectUri(),
    codeVerifier
}: {
    code: string;
    nonce?: string | null;
    redirectUri?: string;
    codeVerifier: string;
}): Promise<{
    sub: string;
    accessToken: string;
}>

Exchanges authorization code for access token.

Parameters

<Object>

• code: <string> Authorization code returned in query params via the redirect URI after login.

• nonce: <string> | <null> (Optional) Nonce returned from authorizationUrl (Set as null if nonce was set as null in authorizationUrl).

• redirectUri: <string> (Optional) Overriding redirect URI used in authorizationUrl (if provided). Defaults to the redirectUri provided in the constructor.

• codeVerifier: <string> Code verifier for the code challenge provided in authorizationUrl.

Throws

Error if call to token endpoint fails.

Error if call to JWKS endpoint fails.

Error if ID token validation fails.

Error if access token validation fails.

Returns

<Promise<Object>>

• sub: <string> Sub (subject identifier claim) which is the end-user's unique ID.

• accessToken: <string> Access token used to request user info.

userinfo

async userinfo({
    sub,
    accessToken
}: {
    sub: string;
    accessToken: string;
}: Promise<{
    sub: string;
    data: Record<string, string>;
}>

Retrieves verified user info and decrypts it with your private key.

Parameters

<Object>

• sub: <string> Sub obtained from callback.

• accessToken: <string> Access token obtained from callback.

Throws

Error if call to userinfo endpoint fails.

Error if sub returned from userinfo endpoint does not match sub passed to this function.

Error if decryption fails.

Returns

<Object>

• sub: <string> Represents a unique identifer for the end-user.

• data: <Record<string, string>> A JSON object containing end-user info where the keys are the scopes requested in authorizationUrl.