SSO (OIDC)

Configure OpenID Connect SSO, generate login URLs, and handle callbacks with the Grantex Python SDK.

Overview

The sso client manages OpenID Connect (OIDC) single sign-on configuration. Set up SSO so your organization’s members can log in through your identity provider (IdP) instead of using API keys directly.

Access the SSO client via client.sso.

Create Config

Create or update the OIDC SSO configuration for your developer organization:

from grantex import Grantex, CreateSsoConfigParams

with Grantex(api_key="gx_live_...") as client:
    config = client.sso.create_config(CreateSsoConfigParams(
        issuer_url="https://accounts.google.com",
        client_id="your-oidc-client-id",
        client_secret="your-oidc-client-secret",
        redirect_uri="https://myapp.com/sso/callback",
    ))

    print(f"Issuer: {config.issuer_url}")
    print(f"Client ID: {config.client_id}")
    print(f"Redirect URI: {config.redirect_uri}")
    print(f"Created at: {config.created_at}")

CreateSsoConfigParams

Field	Type	Required	Description
issuer_url	str	Yes	The OIDC issuer URL (e.g. https://accounts.google.com).
client_id	str	Yes	The OIDC client ID from your IdP.
client_secret	str	Yes	The OIDC client secret from your IdP.
redirect_uri	str	Yes	The redirect URI registered with your IdP.

Get Config

Retrieve the current SSO configuration. The client secret is not included in the response:

config = client.sso.get_config()

print(f"Issuer: {config.issuer_url}")
print(f"Client ID: {config.client_id}")
print(f"Redirect URI: {config.redirect_uri}")
print(f"Updated at: {config.updated_at}")

SsoConfig

Field	Type	Description
issuer_url	str	The OIDC issuer URL.
client_id	str	The OIDC client ID.
redirect_uri	str	The registered redirect URI.
created_at	str	ISO 8601 creation timestamp.
updated_at	str	ISO 8601 last-updated timestamp.

Delete Config

Remove the SSO configuration:

client.sso.delete_config()
# Returns None on success

Get Login URL

Generate the OIDC authorization URL to redirect a user to for SSO login:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    login = client.sso.get_login_url("my-organization")

    print(f"Redirect to: {login.authorize_url}")

Parameters

Parameter	Type	Required	Description
org	str	Yes	The organization identifier for SSO lookup.

SsoLoginResponse

Field	Type	Description
authorize_url	str	The OIDC authorization URL to redirect the user to.

Handle Callback

Exchange the OIDC authorization code for user information after the IdP redirects back to your application:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.sso.handle_callback(
        code="oidc_auth_code",
        state="csrf_state_value",
    )

    print(f"Developer ID: {result.developer_id}")
    print(f"Email: {result.email}")
    print(f"Name: {result.name}")
    print(f"Subject: {result.sub}")

Parameters

Parameter	Type	Required	Description
code	str	Yes	The authorization code from the OIDC callback.
state	str	Yes	The state parameter for CSRF verification.

SsoCallbackResponse

Field	Type	Description
developer_id	str	The Grantex developer ID for the authenticated user.
email	str | None	The user’s email address (if provided by IdP).
name	str | None	The user’s display name (if provided by IdP).
sub	str | None	The OIDC subject identifier.

Complete SSO Flow Example

from grantex import Grantex, CreateSsoConfigParams

with Grantex(api_key="gx_live_...") as client:
    # 1. Configure SSO (one-time setup)
    client.sso.create_config(CreateSsoConfigParams(
        issuer_url="https://accounts.google.com",
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="https://myapp.com/sso/callback",
    ))

    # 2. Generate login URL for a user
    login = client.sso.get_login_url("my-organization")
    # Redirect the user's browser to login.authorize_url

    # 3. Handle the callback (in your /sso/callback route)
    result = client.sso.handle_callback(
        code="code_from_idp",
        state="state_from_idp",
    )
    print(f"Logged in as: {result.email} (developer: {result.developer_id})")

    # 4. Verify or clean up configuration
    config = client.sso.get_config()
    print(f"SSO configured with: {config.issuer_url}")

    # To remove SSO:
    # client.sso.delete_config()