How bitwarden/passwordless-python works
1. This repository is a Python SDK for the Bitwarden Passwordless.dev API, plus two example applications showing how the SDK is used in real apps. The architectural center is the src/passwordless package; everything else either exercises it or demonstrates integration patterns.
2. The core library is split into clear layers:
- client.py is the API boundary and orchestrates HTTP calls.
- config.py holds runtime configuration such as API secret and base URL.
- models.py defines the request/response data structures.
- serialization.py handles JSON marshaling/unmarshaling.
- errors.py centralizes SDK-specific failures and API error mapping.
- __init__.py exposes the public SDK surface.
3. The main dependency direction is one-way: application code creates PasswordlessOptions, builds a PasswordlessClient via PasswordlessClientBuilder, then calls SDK methods like register and sign-in verification. The client talks outward to the Passwordless.dev service over HTTP using requests, and marshmallow is used to convert between Python objects and API JSON.
4. The external system boundary is important: this repo does not implement authentication itself. It is an adapter between a consuming Python application and the hosted Passwordless.dev backend, with the API secret and optional custom API URL defining the deployment/runtime configuration.
5. The SDK’s domain model centers on passkey lifecycle operations: registration token generation and sign-in verification. The README examples show the intended flow: an app creates a user identity, requests a registration token, hands that token to the browser/client, then later verifies a sign-in token and turns the returned verified user into a session or cookie in the host app.
6. The examples/flask subtree shows a classic server-rendered integration. Flask routes and a blueprint (passwordless_bp.py) wrap the SDK, passwordless_api.py/passwordless_api_config.py connect app-specific settings to the SDK client, and static/*.js plus the template passwordless.html handle browser-side interaction. This example demonstrates a split between server API calls and client-side passkey UX.
7. The examples/streamlit subtree shows a different integration style. Streamlit pages (pages/1_sign_in.py, pages/2_register.py) call into a local passwordless_api.py wrapper and also include a small frontend package under passwordless_auth/frontend built with Vite. That makes the example a hybrid of Python app logic and a separate frontend asset build.
8. The examples are not just demos; they define the integration boundary expected by consumers. Each example keeps Passwordless.dev-specific logic isolated in a small adapter layer, so the host app pages/templates stay focused on UI and session handling rather than direct HTTP/API details.
9. Tests are concentrated on the SDK package and validate the contract at the boundaries that matter: client behavior, builder/config wiring, model serialization, and supporting HTTP utilities. The presence of tests/http_utils.py and factory fixtures suggests the test suite mocks external API interactions rather than depending on live Passwordless.dev calls.
10. Tooling and packaging indicate a standard Python library workflow. pyproject.toml, Poetry, and the dev/test instructions define the build/release boundary; .github/workflows/ci.yml and cd.yml provide automated validation and release/deployment; .pre-commit-config.yaml and .flake8 enforce code quality. For an architecture diagram, treat these as supporting infrastructure around the SDK rather than runtime components.
Main entry points: client.py Client · config.py Config · serialization.py Serialization · models.py Models
Components 18
Core SDK
Python library layer that adapts applications to Passwordless.dev.
- Public API · Top-level SDK surface exposed to consumers.
src/passwordless/__init__.py - Client · Orchestrates HTTP calls to the hosted Passwordless.dev service.
src/passwordless/client.py - Config · Holds base URL and secret/options used to configure the client.
src/passwordless/config.py - Models · Request and response objects for passkey lifecycle operations.
src/passwordless/models.py - Serialization · Marshals and unmarshals SDK objects to API JSON.
src/passwordless/serialization.py - Errors · Centralizes SDK failures and API error translation.
src/passwordless/errors.py
Flask Example
Server-rendered integration example with browser-side passkey flow.
- Blueprint · Flask blueprint that wraps SDK actions for the web app.
examples/flask/flaskr/passwordless_bp.py - API wrapper · Application-facing helper around SDK calls and local response handling.
examples/flask/flaskr/passwordless_api.py - App config · Connects Flask app configuration to Passwordless SDK settings.
examples/flask/flaskr/passwordless_api_config.py - Template UI · HTML template for passkey registration and sign-in UX.
examples/flask/flaskr/templates/passwordless.html - Browser JS · Client-side registration, sign-in, and debug behavior.
examples/flask/flaskr/static/client-register.js
Streamlit Example
Hybrid Streamlit app plus separate frontend build.
- Pages · Streamlit sign-in and register pages that drive the example flow.
examples/streamlit/pages/1_sign_in.py - API wrapper · Local helper that bridges Streamlit logic to the SDK.
examples/streamlit/passwordless_api.py - Frontend · Separate frontend asset build used by the Streamlit example.
examples/streamlit/passwordless_auth/frontend/src/main.js
Tooling & Tests
Validation, packaging, and test infrastructure around the SDK.
- Client tests · Validates client behavior and request orchestration.
tests/test_client.py - Builder tests · Checks client builder and configuration wiring.
tests/test_client_builder.py - Model tests · Verifies model and serialization contract.
tests/test_models.py - Build config · Project packaging, dependencies, and library workflow configuration.
pyproject.toml
Connections 20
- Public API → Client: exports · Public package surface exposes the client entry point.
- Public API → Config: exports · Public package surface exposes options/config types.
- Client → Config: uses · Client is built from runtime configuration.
- Client → Models: calls · Client methods operate on request/response models.
- Client → Serialization: serializes · Client converts between Python objects and API payloads.
- Client → Errors: maps errors · API failures are normalized into SDK exceptions.
- Serialization → Models: maps · Serialization layer understands the SDK data structures.
- App config → Config: builds · Example config feeds SDK options into the client builder.
- API wrapper → Client: invokes · Flask adapter calls SDK operations for register and sign-in.
- Blueprint → API wrapper: routes to · Blueprint delegates request handling to the local adapter.
- Blueprint → Template UI: renders · Blueprint serves the passkey UI template.
- Template UI → Browser JS: loads · Template includes browser-side interaction scripts.
- Pages → API wrapper: uses · Pages call the local Streamlit adapter for SDK actions.
- API wrapper → Client: invokes · Streamlit adapter delegates to the SDK client.
- Pages → Frontend: bundles · Example pages pair with the separate frontend asset build.
- Client tests → Client: verifies · Client tests cover request orchestration and boundary behavior.
- Builder tests → Config: verifies · Builder tests cover configuration wiring.
- Model tests → Models: verifies · Model tests cover data shape and serialization contract.
- Model tests → Serialization: verifies · Serialization utilities are exercised by model-focused tests.
- Build config → Client: packages · Build configuration defines the library distribution.