---
title: "sdk/python"
description: "非同期 Python サーバー SDK。ネットワークレス JWT 検証、リクエスト認証、webhook 署名検証をサポートします。"
locale: "ja"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ja/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/python

## 状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 Vonvon インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な \_\_Host-vonvon.rt.\* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

## インストール

```shell
pip install "vonvon @ git+https://github.com/StringKe/vonvon#subdirectory=sdk/python"
```

## クイックスタート

起動時に `VonvonClient` を 1 つ作成して再利用します。クライアントは内部で JWKS をキャッシュします。

```python
from vonvon import VonvonClient

client = VonvonClient(
issuer="https://vonvon.id",
audience="https://api.yourapp.com",  # optional
)

# Verify a token
claims = await client.verify_token("eyJ...")
print(claims.sub, claims.email, claims.scope)

# Authenticate a request (Bearer-only by default)
status = await client.authenticate_request(headers=dict(request.headers))
if not status.authenticated:
raise Unauthorized()
user_id = status.claims.sub

# Explicit same-origin Core session -> JWT exchange
token = await client.exchange_session_token(
incoming_request_url="https://app.example.com/account",
cookie_header=request.headers["cookie"],
)
```

## webhook を検証

```python
from vonvon import WebhookVerificationError

try:
webhook = client.verify_webhook(
    payload=request.body,
    headers=dict(request.headers),
    secret="whsec_xxx",
)
import json
event = json.loads(webhook.body)
except WebhookVerificationError as exc:
raise BadRequest(str(exc))
```

## FastAPI 統合

```python
from fastapi import FastAPI, Depends, HTTPException, Request
from vonvon import VonvonClient, TokenClaims

app = FastAPI()
vonvon = VonvonClient(issuer="https://vonvon.id")

@app.on_event("shutdown")
async def shutdown():
await vonvon.aclose()

async def require_auth(request: Request) -> TokenClaims:
status = await vonvon.authenticate_request(dict(request.headers))
if not status.authenticated:
    raise HTTPException(status_code=401)
return status.claims

@app.get("/me")
async def me(claims: TokenClaims = Depends(require_auth)):
return {"sub": claims.sub, "email": claims.email}
```

## VonvonClient オプション

| パラメーター | デフォルト | 説明 |
| --- | --- | --- |
| `issuer` | 必須 | Vonvon 発行者 URL |
| `audience` | `None` | expected aud クレーム。None は検証をスキップします |
| `jwks_ttl` | `3600` | JWKS メモリ内キャッシュ TTL（秒） |
| `http_timeout` | `10.0` | JWKS 取得タイムアウト（秒） |
| `cookie_name` | `disabled` | アプリケーション所有の JWT cookie 名。明示的に設定した場合のみ有効 |
| `leeway` | `0` | クロックスキュー許容値（秒） |

## コア API

| 方式 | 説明 |
| --- | --- |
| `await client.verify_token(token)` | JWT 文字列を検証します。失敗時は `TokenVerificationError` を発生させます。 |
| `await client.authenticate_request(headers, cookies)` | ヘッダー/Cookie からトークンを取得して検証します。`AuthStatus` を返し、例外を発生させません。 |
| `client.verify_webhook(payload, headers, secret)` | 同期実行。svix HMAC-SHA256 と 5 分間のリプレイウィンドウを検証します。失敗時は `WebhookVerificationError` を発生させます。 |
| `await client.aclose()` | 基礎となる HTTP クライアントリソースを解放します。 |

## プラットフォームの注意事項

- 非同期ファースト。同期呼び出し元（Django/Flask）は `asyncio.run()` でラップできます。
- `pyjwt[crypto] >=2.8` と `httpx >=0.27` が必要です。Python 3.10+ が必要です。
- マルチワーカーデプロイではプロセス間で JWKS キャッシュを共有しません。共有キャッシュ（Redis）は計画中の改善です。

Source: https://vonvon.id/ja/sdks/python/index.mdx