Metadata-Version: 2.5
Name: stwrd
Version: 0.2.0
Summary: SDK de stwrd para Python: login en servidor (ASGI/FastAPI), verify_token y mcp.protect, cliente de gestión generado
Project-URL: Homepage, https://stwrd.id
Project-URL: Repository, https://github.com/mbsm/stwrd
Project-URL: Changelog, https://github.com/mbsm/stwrd/blob/main/sdk/python/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Keywords: asgi,authentication,fastapi,identity,management-api,oidc,stwrd,webhooks
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio<5,>=4
Requires-Dist: authlib<2,>=1.9.1
Requires-Dist: httpx<1,>=0.28
Requires-Dist: joserfc<2,>=1.7.6
Requires-Dist: standardwebhooks<2,>=1.1
Requires-Dist: starlette<2,>=1.7
Description-Content-Type: text/markdown

# stwrd

Python SDK for stwrd: server-side login (ASGI/FastAPI), `verify_token`,
`mcp.protect` and a generated management client.

```sh
pip install stwrd
```

Python 3.11 or newer.

## Management client

Async client for the Management API, authenticated with an API key
(`<client_id>.<secret>`). It reads `STWRD_API_KEY` and `STWRD_ISSUER` from the
environment by default and fails closed when they are missing or malformed.

```python
from stwrd.management import ConflictError, create_management

async with create_management() as mgmt:
    # Resources with an ETag return WithEtag(data=..., etag=...).
    res = await mgmt.users.get("usr_123")
    print(res.data["email"])

    # Optimistic concurrency: pass the ETag you read. A change in between raises ConflictError (412).
    try:
        await mgmt.users.update("usr_123", {"locale": "es"}, if_match=res.etag)
    except ConflictError:
        ...  # re-read and decide again

    # Without if_match the write has no condition: the last write wins.
    await mgmt.users.update("usr_123", {"locale": "es"})

    # Lists are paginated; async for walks every page.
    async for user in mgmt.users.list(limit=50):
        print(user["id"])
```

- `get` on agents, API keys, applications, managed key grants, organizations,
  the tenant, users and webhook endpoints returns `WithEtag`. `etag` is `""` if
  the server sent none. Everything else returns the body directly.
- The client never reads the ETag by itself: `if_match` is sent only when you
  pass it.
- Errors derive from `StwrdApiError` (`status`, `code`, `request_id`,
  `details`): `ConflictError` (412), `UserExistsError` and `LimitExceededError`
  (409). A bad configuration raises `ManagementConfigError`.
- Retries (up to 3, growing wait, honors `Retry-After`; on 429, 502, 503, 504
  and network errors): reads, deletes and `POST` (the `Idempotency-Key` is added
  automatically and reused) are retried. An unconditional `PATCH`/`PUT` (no
  `if_match`, or `*`) is retried only if the request was never sent.
- An API key gets `403 step_up_required` on routes that need a recent second
  factor (webhooks, mail provider, secrets, administrators, signing keys, key
  management, deleting applications, users or the tenant). Do those from the
  dashboard.

See https://stwrd.id for documentation.

## License

MIT
