ThunderID Python SDK

[sahandilshan]

Summary

Introduce an official Python SDK for backend services, scripts, automation, and AI applications.

The SDK will follow the SDK development specification, providing idiomatic Python APIs, type annotations, async support, and secure token handling.

Related issue: #2530.

Motivation

Python developers currently need to implement authentication requests, token handling, and session management themselves. An official SDK would provide a consistent foundation for authenticating users, services, and agents, including delegated access.

Proposed design

Architecture and packaging

The SDK will live in a separate python-sdks repository and be distributed as thunderid, subject to package-name availability.

The proposal is to support Python 3.11+ with an async-first client. One package will cover the Agnostic and Platform layers, keeping protocol logic separate internally from HTTP transport and storage. Future framework integrations can build on this package.

Authentication and client APIs

The SDK will support:

• Authorization code with PKCE for interactive authentication.
• Embedded authentication and registration through server-defined flows.
• Client credentials for services and agents acting as themselves.
• Delegated access through interactive sign-in, CIBA, or token exchange.
• CIBA for out-of-band user authentication.

It will implement the specification’s required authentication, configuration, session, token, user, and profile operations using Python naming conventions.

Convenience methods such as get_agent_token and get_obo_token will make common agent authentication and delegated-access scenarios straightforward. These will reuse the underlying protocol implementation and keep authorization context explicit.

OBO will not be treated as synonymous with token exchange. A user can also sign in through the requesting application or agent’s registered client, or authenticate through CIBA, to establish delegated access.

Sessions and security

Each authentication context will isolate its tokens and sessions. Tokens belonging to different users, agents, or resources must not overwrite one another.

The SDK will handle token renewal, concurrent refresh deduplication, atomic storage updates, and sign-out according to the shared specification. OS keyring will provide default secure storage, with a replaceable adapter for application-specific deployments.

Security behavior will include PKCE, callback state validation, endpoint trust checks, ID-token validation, TLS verification, and exclusion of credentials and tokens from logs and errors. Failures will follow the shared ThunderIDError hierarchy.

Documentation and testing

The SDK will ship with a quickstart, API reference, security guidance, and runnable examples covering user authentication, service and agent authentication, and delegated access.

Published documentation will live in the ThunderID product repository, while SDK samples will live alongside the package.

Validation will include offline unit tests, security regression tests, and end-to-end tests against a provisioned ThunderID server. CI will cover linting, type checking, tests, builds, and SDK parity requirements.

Initial scope

The first release will focus on authentication and identity. Framework-specific packages, bundled UI, management APIs, and back-channel logout are outside the initial scope.

Companion updates to the shared specification will document Python packaging and any new public APIs or behavior. The threat model and cross-SDK parity decisions will be updated where required.

Questions for discussion

1. Should the initial release include both synchronous and asynchronous clients?
2. Is Python 3.11 an appropriate minimum supported version?
3. Are the proposed scope and convenience APIs sufficient for common Python use cases?