docs(examples): add comprehensive authentication flow examples

- Add a user login example that automatically selects between browser-based auth and device code flow
- Add a client credentials example demonstrating machine-to-machine token fetching and caching
- Add a FastAPI server example with bearer token validation and optional scope enforcement
- Add an async login example using the device code flow for asynchronous environments

Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>

Author: appleboy

examples/01_user_login.py

@@ -0,0 +1,37 @@
+"""Example 1: User login with automatic flow selection.
+
+Tries browser (Auth Code + PKCE) first; falls back to Device Code flow
+when no browser is available (e.g., SSH sessions, CI).
+
+Usage:
+    uv run python examples/01_user_login.py
+"""
+
+from __future__ import annotations
+
+import os
+
+import authgate
+
+AUTHGATE_URL = os.environ["AUTHGATE_URL"]
+CLIENT_ID = os.environ["CLIENT_ID"]
+
+
+def main() -> None:
+    # authenticate() caches the token on disk and refreshes it automatically.
+    client, token = authgate.authenticate(
+        AUTHGATE_URL,
+        CLIENT_ID,
+        scopes=["openid", "profile", "email"],
+    )
+
+    print(f"Logged in!  access_token={token.access_token[:20]}...")
+
+    # Use the client to call an OAuth endpoint (e.g., UserInfo).
+    userinfo = client.userinfo(token.access_token)
+    print(f"Subject : {userinfo.get('sub')}")
+    print(f"Email   : {userinfo.get('email')}")
+
+
+if __name__ == "__main__":
+    main()

examples/02_client_credentials.py

@@ -0,0 +1,46 @@
+"""Example 2: Machine-to-machine (M2M) with Client Credentials grant.
+
+Tokens are cached in memory and refreshed automatically before expiry.
+No user interaction is required.
+
+Usage:
+    uv run python examples/02_client_credentials.py
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from authgate.clientcreds.token_source import TokenSource
+from authgate.discovery.client import DiscoveryClient
+from authgate.oauth.client import OAuthClient
+
+AUTHGATE_URL = os.environ["AUTHGATE_URL"]
+CLIENT_ID = os.environ["AUTHGATE_CLIENT_ID"]
+CLIENT_SECRET = os.environ["AUTHGATE_CLIENT_SECRET"]
+API_URL = "https://api.example.com/data"
+
+
+def make_token_source() -> TokenSource:
+    meta = DiscoveryClient(AUTHGATE_URL).fetch()
+    client = OAuthClient(CLIENT_ID, meta.to_endpoints(), client_secret=CLIENT_SECRET)
+    return TokenSource(client, scopes=["api:read"])
+
+
+def main() -> None:
+    ts = make_token_source()
+
+    # ts.token() returns a cached token and only fetches a new one when needed.
+    token = ts.token()
+    print(f"Access token: {token.access_token[:20]}...")
+
+    # Attach the token to an outbound HTTP request.
+    headers = {"Authorization": f"Bearer {token.access_token}"}
+    resp = httpx.get(API_URL, headers=headers, timeout=10)
+    print(f"API response: {resp.status_code}")
+
+
+if __name__ == "__main__":
+    main()

examples/03_fastapi_server.py

@@ -0,0 +1,59 @@
+"""Example 3: FastAPI server with Bearer token validation.
+
+Every protected route requires a valid Bearer token issued by AuthGate.
+Optional scope enforcement is shown on /admin.
+
+Install extras:
+    uv pip install authgate[fastapi]
+
+Run:
+    uv run uvicorn examples.03_fastapi_server:app --reload
+"""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import Depends, FastAPI
+
+from authgate.discovery.client import DiscoveryClient
+from authgate.middleware.fastapi import BearerAuth
+from authgate.middleware.models import TokenInfo
+from authgate.oauth.client import OAuthClient
+
+AUTHGATE_URL = os.environ["AUTHGATE_URL"]
+CLIENT_ID = os.environ["AUTHGATE_CLIENT_ID"]
+
+# Build shared OAuth client once at startup.
+_meta = DiscoveryClient(AUTHGATE_URL).fetch()
+_oauth = OAuthClient(CLIENT_ID, _meta.to_endpoints())
+
+# Reusable dependency — validates any Bearer token.
+bearer_auth = BearerAuth(_oauth)
+
+# Dependency that also enforces a specific scope.
+admin_auth = BearerAuth(_oauth, required_scopes=["admin"])
+
+app = FastAPI(title="AuthGate FastAPI Example")
+
+
+@app.get("/me")
+async def get_me(token_info: TokenInfo = Depends(bearer_auth)) -> dict[str, object]:
+    """Return the token's subject and scopes."""
+    return {
+        "sub": token_info.sub,
+        "scopes": token_info.scopes,
+        "active": token_info.active,
+    }
+
+
+@app.get("/admin")
+async def admin_endpoint(token_info: TokenInfo = Depends(admin_auth)) -> dict[str, str]:
+    """Only accessible with the 'admin' scope."""
+    return {"message": f"Hello admin {token_info.sub}!"}
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    """Public endpoint — no auth required."""
+    return {"status": "ok"}

examples/04_async_login.py

@@ -0,0 +1,35 @@
+"""Example 4: Async user login with Device Code flow.
+
+Useful inside async applications (e.g., async CLI tools, Jupyter notebooks).
+Auth Code + PKCE is not available in async mode; Device Code is always used.
+
+Usage:
+    uv run python examples/04_async_login.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+import authgate
+
+AUTHGATE_URL = os.environ["AUTHGATE_URL"]
+CLIENT_ID = os.environ["AUTHGATE_CLIENT_ID"]
+
+
+async def main() -> None:
+    client, token = await authgate.async_authenticate(
+        AUTHGATE_URL,
+        CLIENT_ID,
+        scopes=["openid", "profile"],
+    )
+
+    print(f"Logged in!  access_token={token.access_token[:20]}...")
+
+    userinfo = await client.userinfo(token.access_token)
+    print(f"Subject: {userinfo.get('sub')}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())