# API Reference

This page contains comprehensive API documentation for the Python SDK. If you're looking to get started quickly, visit our [quick start](https://docs.id.gov.sg/integrations-with-sgid/python) or our [framework-specific guides](https://docs.id.gov.sg/integrations-with-sgid/python/framework-guides).

The source code can be found on [GitHub](https://github.com/opengovsg/sgid-client-python).

## convert\_to\_pkcs8

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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.