konecty_sdk_python

Konecty Python SDK

🛠️ Work in progress

This project exposes both:

a cli for interacting with the database
the Konecty client sdk for interacting with Konecty's api

Usage

Installing on a project

uv pip install konecty-sdk-python
konecty-cli apply --mongo-url="..." --database my-db

Running on uvx

uvx --from konecty-sdk-python konecty-cli pull --all --mongo-url="..." --database my-db

Google login

The Konecty core hosts the whole authorization code flow: your app never talks to Google and never sees client_secret. The authId never travels in a URL — the callback returns a single-use code (TTL 60s) and the authId only exists in the body of POST /api/auth/google/session.

Three steps, three methods:

client.google_login_url(...) — build the URL to send the browser to (no request is made).
the browser comes back to your redirect_uri with ?code=...&state=... (or ?error=...&state=...).
await client.exchange_google_code(code) — turn the code into a session; the returned authId is adopted by the client, so the next calls are authenticated.

import asyncio
import os
import secrets

from KonectySdkPython import KonectyClient
from KonectySdkPython.lib.exceptions import KonectyAPIError

KONECTY_URL = os.environ["KONECTY_URL"]
CLIENT_ID = os.environ["KONECTY_CLIENT_ID"]
REDIRECT_URI = os.environ["KONECTY_REDIRECT_URI"]


async def main() -> None:
    client = KonectyClient(KONECTY_URL)

    # Is Google login enabled for this namespace?
    options = await client.get_login_options()
    if not options["googleEnabled"]:
        raise SystemExit("Google login is disabled for this namespace")

    # Step 1 — send the browser here (state is opaque to Konecty; use it against CSRF).
    state = secrets.token_urlsafe(16)
    print(client.google_login_url(client_id=CLIENT_ID, redirect_uri=REDIRECT_URI, state=state))

    # Step 2 — Konecty redirects the browser back to REDIRECT_URI with code + state.
    #          On refusal it comes back as ?error=<access_denied|provider_error|
    #          email_not_verified|user_not_found|user_inactive|ambiguous_user>&state=...
    returned_code = input("code from the callback: ")

    # Step 3 — exchange the single-use code for a session.
    try:
        session = await client.exchange_google_code(
            returned_code,
            source="my-app",  # optional telemetry: geolocation, resolution, source, fingerprint
        )
    except KonectyAPIError as error:
        raise SystemExit(f"Google login failed: {error}")

    print("logged as", session["user"]["login"], "authId:", client.auth_id)

    # The client is now authenticated: no token needed on the constructor.
    contacts = await client.find_by_id("User", session["user"]["_id"])
    print(contacts)


asyncio.run(main())

exchange_google_code raises KonectyAPIError with the message of errors[0] (invalid_code, expired_code, user_not_found, user_inactive) and leaves the client's authentication state untouched.

Tests

uv pip install -e ".[dev]"
.venv/bin/python -m pytest

Build & Publish

It is needed to increase the version number on the pyproject file.

uv build
uvx twine upload --config-file .pypirc --skip-existing dist/*

Metadata

Release files for konecty_sdk_python 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for konecty_sdk_python 2.1.0
File	Size	Uploaded
konecty_sdk_python-2.1.0.tar.gz	34.2 kB	Jul 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for konecty_sdk_python 2.1.0
File	Interpreter	ABI	Platform	Reset
konecty_sdk_python-2.1.0-py3-none-any.whl 49.3 kB Jul 30, 2026	Python 3	none	any	Details

Total release size: 83.6 kB

Release files / konecty_sdk_python-2.1.0.tar.gz

Download URL	konecty_sdk_python-2.1.0.tar.gz
Size	34.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`e20f4e106689b92bd7c0ea0a09cc9d5ba558843dadd522c0b0dc167fc322ddf4`
BLAKE2b-256 checksum How to use checksums	`3df8eb2b95f064fff08c894243492d06da3ec86f7fb5e594912bf287125bc48b`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.11`

Release files / konecty_sdk_python-2.1.0-py3-none-any.whl

Download URL	konecty_sdk_python-2.1.0-py3-none-any.whl
Size	49.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`210b6c4f42cb40c2b541b8203fec0148ad677652d5f6a5ef1aed6fed715c6211`
BLAKE2b-256 checksum How to use checksums	`b939c6ec7327650388aa391a7878b388462edf52ea39c1a0956a8b2f1c49443b`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.11`