API Reference

This page contains comprehensive API documentation for the Python 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.

convert_to_pkcs8

convert_to_pkcs8(private_key: str) -> str

Converts a private key in PKCS1 format to PKCS8.

Args

private_key (str) Private key as a string.

Raises

Exception if private key is invalid.

Returns

str Private key in PKCS8 format.

generate_code_challenge

generate_code_challenge(code_verifier: str) -> str

Calculates the S256 code challenge for a provided code verifier.

Args

code_verifier (str) The code verifier.

Returns

str The calculated code challenge.

generate_code_verifier

generate_code_verifier(length=43) -> str

Generates the random code verifier.

Args

length (int, optional) The length of the code verifier to generate. Defaults to 43.

Raises

Exception if length is <43 or >128.

Returns

str: The generated code verifier.

generate_pkce_pair

generate_pkce_pair(length=43) -> GeneratePkcePairReturn

class GeneratePkcePairReturn(NamedTuple):
    code_verifier: str
    code_challenge: str

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

Args

length (int, optional) The length of the code verifier. Defaults to 43.

Raises

Exception if length is <43 or >128.

Returns

GeneratePkcePairReturn: Code challenge and code verifier.

SgidClient

Class which allows you to interact with the sgID API.

Constructor

SgidClient(
    client_id: str,
    client_secret: str,
    private_key: str,
    redirect_uri: str | None = None,
    hostname: str = "https://api.id.gov.sg",
)

Initialises an SgidClient instance.

Args

client_id (str) Client ID provided during client registration.

client_secret (str) Client secret provided during client registration.

private_key (str) Client private key provided during client registration.

redirect_uri (str | None, 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. Defaults to None.

hostname (str, optional) Hostname of OpenID provider (sgID). Defaults to "https://api.id.gov.sg".

Raises

Exception if private key is invalid.

authorization_url

authorization_url(
    code_challenge: str,
    state: str | None = None,
    redirect_uri: str | None = None,
    scope: str | list[str] = "openid myinfo.name",
    nonce: str | None = secrets.token_urlsafe(32),
) -> AuthorizationUrlReturn

class AuthorizationUrlReturn(NamedTuple):
    url: str
    nonce: str | None

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

Args

code_challenge (str) The code challenge generated from generate_pkce_pair().

state (str | None, 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.

redirect_uri (str | None, 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 None.

scope (str | list[str]) "openid" must be provided as a scope. Defaults to "openid myinfo.name".

nonce (str | None, optional) Unique nonce for this request. If this param is not provided, a nonce is generated and returned. To prevent this behaviour, specify None for this param. Defaults to secrets.token_urlsafe(32).

Raises

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

Returns

AuthorizationUrlReturn: Authorization URL and nonce.

callback

callback(
    code: str,
    code_verifier: str,
    nonce: str | None = None,
    redirect_uri: str | None = None,
) -> CallbackReturn

class CallbackReturn(NamedTuple):
    sub: str
    access_token: str

Exchanges authorization code for access token.

Args

code (str) The authorization code received from the authorization server.

code_verifier (str) The code verifier corresponding to the code challenge that was passed to authorization_url for this request.

nonce (str | None, optional) Nonce passed to authorization_url for this request. Specify None if no nonce was passed to authorization_url. Defaults to None.

redirect_uri (str | None, optional) The redirect URI used in the authorization request. If not specified, defaults to the one passed to the SgidClient constructor.

Raises

Exception if call to token endpoint fails.

Exception if call to JWKS endpoint fails.

Exception if ID token validation fails.

Exception if access token validation fails.

Returns

CallbackReturn: The sub (subject identifier claim) of the user and access token. The subject identifier claim is the end-user's unique ID.

userinfo

userinfo(sub: str, access_token: str) -> UserInfoReturn

class UserInfoReturn(NamedTuple):
    sub: str
    data: dict

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

Args

sub (str) The sub returned from the callback function.

access_token (str) The access token returned from the callback function.

Raises

Exception if call to userinfo endpoint fails.

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

Exception if decryption fails.

Returns

UserInfoReturn: The sub of the end-user and the end-user's verified data. The sub returned is the same as the one passed in the params.