# bitwarden/passwordless-python architecture

> Architecture diagram of the GitHub repository bitwarden/passwordless-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bitwarden/passwordless-python
- Repository: https://github.com/bitwarden/passwordless-python

## Overview

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: [`src/passwordless/client.py`](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/client.py) (Client), [`src/passwordless/config.py`](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/config.py) (Config), [`src/passwordless/serialization.py`](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/serialization.py) (Serialization), [`src/passwordless/models.py`](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/models.py) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core_sdk["Core SDK"]
  node_sdk_init["Public API<br/>package export<br/>[__init__.py]"]
  node_sdk_client["Client<br/>API boundary<br/>[client.py]"]
  node_sdk_config["Config<br/>runtime settings<br/>[config.py]"]
  node_sdk_models["Models<br/>[models.py]"]
  node_sdk_serialization["Serialization<br/>json mapping<br/>[serialization.py]"]
  node_sdk_errors["Errors<br/>error mapping<br/>[errors.py]"]
end

subgraph group_flask_example["Flask Example"]
  node_flask_bp["Blueprint<br/>route adapter<br/>[passwordless_bp.py]"]
  node_flask_api["API wrapper<br/>app adapter"]
  node_flask_cfg["App config<br/>app settings"]
  node_flask_ui["Template UI<br/>server template<br/>[passwordless.html]"]
  node_flask_js["Browser JS<br/>client scripts<br/>[client-register.js]"]
end

subgraph group_streamlit_example["Streamlit Example"]
  node_streamlit_pages["Pages<br/>[1_sign_in.py]"]
  node_streamlit_api["API wrapper<br/>app adapter"]
  node_streamlit_ui["Frontend<br/>vite app<br/>[main.js]"]
end

subgraph group_tooling_tests["Tooling & Tests"]
  node_tests_client["Client tests<br/>unit tests<br/>[test_client.py]"]
  node_tests_builder["Builder tests<br/>unit tests"]
  node_tests_models["Model tests<br/>unit tests<br/>[test_models.py]"]
  node_pyproject["Build config<br/>packaging<br/>[pyproject.toml]"]
end

node_sdk_init -->|"exports"| node_sdk_client
node_sdk_init -->|"exports"| node_sdk_config
node_sdk_client -->|"uses"| node_sdk_config
node_sdk_client -->|"calls"| node_sdk_models
node_sdk_client -->|"serializes"| node_sdk_serialization
node_sdk_client -->|"maps errors"| node_sdk_errors
node_sdk_serialization -->|"maps"| node_sdk_models
node_flask_cfg -->|"builds"| node_sdk_config
node_flask_api -->|"invokes"| node_sdk_client
node_flask_bp -->|"routes to"| node_flask_api
node_flask_bp -->|"renders"| node_flask_ui
node_flask_ui -->|"loads"| node_flask_js
node_streamlit_pages -->|"uses"| node_streamlit_api
node_streamlit_api -->|"invokes"| node_sdk_client
node_streamlit_pages -->|"bundles"| node_streamlit_ui
node_tests_client -->|"verifies"| node_sdk_client
node_tests_builder -->|"verifies"| node_sdk_config
node_tests_models -->|"verifies"| node_sdk_models
node_tests_models -->|"verifies"| node_sdk_serialization
node_pyproject -->|"packages"| node_sdk_client

click node_sdk_init "https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/__init__.py"
click node_sdk_client "https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/client.py"
click node_sdk_config "https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/config.py"
click node_sdk_models "https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/models.py"
click node_sdk_serialization "https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/serialization.py"
click node_sdk_errors "https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/errors.py"
click node_flask_bp "https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/passwordless_bp.py"
click node_flask_api "https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/passwordless_api.py"
click node_flask_cfg "https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/passwordless_api_config.py"
click node_flask_ui "https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/templates/passwordless.html"
click node_flask_js "https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/static/client-register.js"
click node_streamlit_pages "https://github.com/bitwarden/passwordless-python/blob/main/examples/streamlit/pages/1_sign_in.py"
click node_streamlit_api "https://github.com/bitwarden/passwordless-python/blob/main/examples/streamlit/passwordless_api.py"
click node_streamlit_ui "https://github.com/bitwarden/passwordless-python/blob/main/examples/streamlit/passwordless_auth/frontend/src/main.js"
click node_tests_client "https://github.com/bitwarden/passwordless-python/blob/main/tests/test_client.py"
click node_tests_builder "https://github.com/bitwarden/passwordless-python/blob/main/tests/test_client_builder.py"
click node_tests_models "https://github.com/bitwarden/passwordless-python/blob/main/tests/test_models.py"
click node_pyproject "https://github.com/bitwarden/passwordless-python/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk_init,node_sdk_client,node_sdk_config,node_sdk_models,node_sdk_serialization,node_sdk_errors toneBlue
class node_flask_bp,node_flask_api,node_flask_cfg,node_flask_ui,node_flask_js toneAmber
class node_streamlit_pages,node_streamlit_api,node_streamlit_ui toneMint
class node_tests_client,node_tests_builder,node_tests_models,node_pyproject toneRose
```

## Components

### Core SDK

Python library layer that adapts applications to Passwordless.dev.

- [Public API](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/__init__.py): package export · Top-level SDK surface exposed to consumers. · `src/passwordless/__init__.py`
- [Client](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/client.py): API boundary · Orchestrates HTTP calls to the hosted Passwordless.dev service. · `src/passwordless/client.py`
- [Config](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/config.py): runtime settings · Holds base URL and secret/options used to configure the client. · `src/passwordless/config.py`
- [Models](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/models.py): data models · Request and response objects for passkey lifecycle operations. · `src/passwordless/models.py`
- [Serialization](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/serialization.py): json mapping · Marshals and unmarshals SDK objects to API JSON. · `src/passwordless/serialization.py`
- [Errors](https://github.com/bitwarden/passwordless-python/blob/main/src/passwordless/errors.py): error mapping · Centralizes SDK failures and API error translation. · `src/passwordless/errors.py`

### Flask Example

Server-rendered integration example with browser-side passkey flow.

- [Blueprint](https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/passwordless_bp.py): route adapter · Flask blueprint that wraps SDK actions for the web app. · `examples/flask/flaskr/passwordless_bp.py`
- [API wrapper](https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/passwordless_api.py): app adapter · Application-facing helper around SDK calls and local response handling. · `examples/flask/flaskr/passwordless_api.py`
- [App config](https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/passwordless_api_config.py): app settings · Connects Flask app configuration to Passwordless SDK settings. · `examples/flask/flaskr/passwordless_api_config.py`
- [Template UI](https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/templates/passwordless.html): server template · HTML template for passkey registration and sign-in UX. · `examples/flask/flaskr/templates/passwordless.html`
- [Browser JS](https://github.com/bitwarden/passwordless-python/blob/main/examples/flask/flaskr/static/client-register.js): client scripts · 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](https://github.com/bitwarden/passwordless-python/blob/main/examples/streamlit/pages/1_sign_in.py): app pages · Streamlit sign-in and register pages that drive the example flow. · `examples/streamlit/pages/1_sign_in.py`
- [API wrapper](https://github.com/bitwarden/passwordless-python/blob/main/examples/streamlit/passwordless_api.py): app adapter · Local helper that bridges Streamlit logic to the SDK. · `examples/streamlit/passwordless_api.py`
- [Frontend](https://github.com/bitwarden/passwordless-python/blob/main/examples/streamlit/passwordless_auth/frontend/src/main.js): vite app · 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](https://github.com/bitwarden/passwordless-python/blob/main/tests/test_client.py): unit tests · Validates client behavior and request orchestration. · `tests/test_client.py`
- [Builder tests](https://github.com/bitwarden/passwordless-python/blob/main/tests/test_client_builder.py): unit tests · Checks client builder and configuration wiring. · `tests/test_client_builder.py`
- [Model tests](https://github.com/bitwarden/passwordless-python/blob/main/tests/test_models.py): unit tests · Verifies model and serialization contract. · `tests/test_models.py`
- [Build config](https://github.com/bitwarden/passwordless-python/blob/main/pyproject.toml): packaging · Project packaging, dependencies, and library workflow configuration. · `pyproject.toml`

## Connections

- 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.
