Metadata-Version: 2.4
Name: waona-identity-sdk
Version: 0.2.0
Summary: Verify WAONA Identity access tokens in Python APIs, with FastAPI integration
Author-email: WAONA Technologies <hello@waona.ke>
License-Expression: MIT
Project-URL: Homepage, https://waona.ke/identity
Project-URL: Documentation, https://waona.ke/identity/docs
Keywords: waona,identity,oidc,oauth2,jwt,fastapi,authentication
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: src/waona_identity_sdk/LICENSE
Requires-Dist: PyJWT[crypto]<3.0,>=2.10
Requires-Dist: fastapi<1.0,>=0.115
Provides-Extra: dev
Requires-Dist: httpx<1.0,>=0.27; extra == "dev"
Requires-Dist: pytest<10.0,>=8.0; extra == "dev"
Dynamic: license-file

# waona-identity-sdk

Verify [WAONA Identity](https://waona.ke/identity) access tokens in Python APIs.

```bash
pip install waona-identity-sdk
```

## Protect a FastAPI API

```python
from fastapi import Depends, FastAPI
from waona_identity_sdk import Identity, TokenVerifier, create_current_identity_dependency

verifier = TokenVerifier.discover(
    "https://identity.waona.ke/realms/t-acme-prod",  # your environment's issuer
    audience="acme-orders",                          # the API identifier you registered
)
current_identity = create_current_identity_dependency(verifier)
app = FastAPI()

@app.get("/me")
def me(identity: Identity = Depends(current_identity)):
    return {"id": identity.subject, "email": identity.email}
```

Every request is checked for signature, issuer, audience, expiry and token type.
Missing or invalid tokens get `401`; ID tokens are rejected.

## Require scopes

```python
from waona_identity_sdk import require_scopes

@app.post("/orders")
def create(identity: Identity = Depends(require_scopes(current_identity, "orders:write"))):
    ...
```

## Test without a server

```python
from waona_identity_sdk.testing import TestIssuer

issuer = TestIssuer()
verifier = issuer.verifier(audience="acme-orders")
token = issuer.token(subject="user-1", audience="acme-orders", scope="openid orders:write")
```

`Identity` exposes `subject`, `issuer`, `email`, `email_verified`, `name`, `username`,
`scopes` and the raw `claims`. Store `subject` (with the issuer) as the user's ID, not the email.

## License

MIT. The SDK is open source; the WAONA Identity service itself is proprietary.
