# Python

## Installation

```bash
pip install sgid-client
```

## Framework guides

If you are using one of the Python frameworks below, you may refer to our in-depth guide:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td></td><td><img src="https://2214909052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBW92htBuXTrDYoKovQ2%2Fuploads%2FGiwHbcoY66vNKV71wy7q%2Fflask-horizontal.webp?alt=media&#x26;token=e86254d5-0ea3-44e7-bfa0-d1d7ce217264" alt=""></td><td>Flask (with Single-Page App frontend)<br></td><td><a href="python/framework-guides/flask-with-single-page-app-frontend">flask-with-single-page-app-frontend</a></td></tr></tbody></table>

If not, read on for a framework-agnostic Quick Start in the next section.

## Quick start

The **sgID SDK is meant to be used within server-side code** (i.e. your backend code). As such, the following steps contain code snippets that should only be run on the server. If you would like to view more details about how your frontend should interact with your backend, please view one of our [Framework Guides](#framework-guides).

### Step 1: Initialize the SDK

{% hint style="info" %}
If you have not already obtained your client credentials via registration, please [register your client](https://docs.id.gov.sg/introduction/getting-started/register-your-application) before proceeding.
{% endhint %}

```python
sgid_client = SgidClient(
    client_id=os.getenv("SGID_CLIENT_ID"),
    client_secret=os.getenv("SGID_CLIENT_SECRET"),
    private_key=os.getenv("SGID_PRIVATE_KEY"),
    redirect_uri=os.getenv("SGID_REDIRECT_URI"),
)
```

{% hint style="info" %}
Load your sgID credentials in a secure way using environment variables instead of hard-coding them into your app.
{% endhint %}

### Step 2: Generate a code verifier and challenge pair

You should generate a new pair for each authorization request, and store the code verifier somewhere you can retrieve it when your user returns from logging into sgID (e.g. in the user's session).

```python
from sgid_client import generate_pkce_pair

code_verifier, code_challenge = generate_pkce_pair()
```

### Step 3: Generate the authorization URL

```python
url, nonce = sgid_client.authorization_url(
    code_challenge=pkce_pair["code_challenge"],
    scope = "openid myinfo.name", # replace this with your own scope
)
```

You should store the nonce somewhere you can retrieve it when your user returns from logging into sgID, likely in the same place that you store the code verifier.

### Step 4: Receive the callback

After your user logs in to sgID, they will be redirected to your redirect URI with the authorization code (`code`) in the query parameters. At this point, you should retrieve the code verifier and nonce from where they were stored in steps 2 and 3 respectively.

```python
sub, access_token = sgid_client.callback(
    code=code, code_verifier=code_verifier, nonce=nonce
)
```

The `sub` is an end-user's unique sgID identifier, and is used together with the access token in the next step to retrieve the user's data. Feel free to use the `sub` to identify your user in your application as necessary.

### Step 5: Retrieve the data

The final step is to retrieve the data, which will contain the scopes requested in step 3.

```python
sub, data = sgid_client.userinfo(sub=sub, access_token=access_token)
```

## API reference

For more detailed documentation for each function, visit our [API reference](https://docs.id.gov.sg/integrations-with-sgid/python/api-reference).