Introducing the AgentOnboard Python SDK

Python is the default language of the AI ecosystem. Most autonomous agents, tool backends, and agentic workflows run on FastAPI, Flask, and Django.

Until today, integrating AgentOnboard into a Python service meant hand-rolling cryptographic verification: fetching JWKS sets, configuring in-process key caching, enforcing RS256 algorithm pinning, handling clock skew, normalizing hostnames, and wiring error status codes.

Today we shipped the official Python partner SDK: agentonboard-sdk, available now on PyPI.

pip install "agentonboard-sdk[fastapi]"

It brings the same cryptographic guarantees and zero-configuration resilience from our TypeScript core to Python web services.

---

3 Lines to Guard a FastAPI Endpoint#

The SDK exports AgentBearerAuth, a drop-in FastAPI security dependency that handles token extraction, key fetching, signature checks, and error responses:

from fastapi import Depends, FastAPI
from agentonboard import AgentIdentity
from agentonboard.frameworks.fastapi import AgentBearerAuth

app = FastAPI(title="Notes API")

# Target audience matches your public service domain
auth = AgentBearerAuth(audience="notes.com")

@app.get("/api/notes")
async def list_notes(identity: AgentIdentity = Depends(auth)):
    return {"message": f"Hello, {identity.email}"}

When an agent calls /api/notes with an Authorization: Bearer <token> header:

1. The SDK verifies the signature locally against AgentOnboard public keys.
2. It verifies that the audience exactly matches notes.com (preventing token reuse across services).
3. It validates expiry (exp) within a 5-second clock skew tolerance.
4. Your handler receives an AgentIdentity with the verified human email.

If the token is expired or altered, FastAPI automatically returns 401 Unauthorized with a structured error payload so the agent can refresh its session and retry.

---

Account Resolution and Provisioning#

Authentication proves identity; your database decides permissions.

With verify_agent_account and create_agent_account, the SDK lets you map the verified email to your own internal database user in one step:

from fastapi import Depends, FastAPI
from agentonboard import AgentIdentity
from agentonboard.frameworks.fastapi import AgentBearerAuth

# Resolve existing users from your database
async def get_user_by_email(identity: AgentIdentity):
    return await db.users.find_one({"email": identity.email.lower()})

# Provision new accounts for first-time agents
async def create_user_for_agent(identity: AgentIdentity):
    return await db.users.insert_one({"email": identity.email.lower()})

auth = AgentBearerAuth(
    audience="notes.com",
    resolver=get_user_by_email,
    creator=create_user_for_agent,
    auto_create=True,
)

@app.post("/api/notes")
async def create_note(user = Depends(auth)):
    return {"success": True, "user_id": str(user["_id"])}

If auto_create is disabled and an unknown email arrives, the endpoint returns 403 Forbidden with {"code": "ACCOUNT_REQUIRED"}. Agents recognize this code and direct the human user to connect their account.

---

Flask, Django, and Sync Runtimes#

Python backends are split between async and sync runtimes. agentonboard-sdk natively supports both:

• Flask: Use the @require_agent_token(audience="...") route decorator.
• Django / Celery / Scripts: Call verify_agent_token or verify_agent_account synchronously without event loop conflicts.

from agentonboard import verify_agent_token

result = verify_agent_token(
    token=raw_token,
    audience="notes.com",
)

if result.ok:
    print(f"Authenticated human: {result.email}")
else:
    print(f"Rejected: {result.code} - {result.error}")

---

What the SDK Guarantees#

Every language port of AgentOnboard must satisfy our conformance test suite (agent-token-v1.json):

1. Algorithm Pinning: The verifier only verifies RS256. The algorithm header in the incoming JWT is never trusted, eliminating algorithm-confusion attacks.
2. Bounded Key Cache: Public keys are held in an in-process LRU cache bounded to 8 sources. It will not grow unbounded in multi-tenant environments.
3. Network Resilience: If the JWKS endpoint suffers a transient outage, the SDK falls back to the last-known-good key set rather than failing live user requests.
4. Unknown Key Cooldown: Unrecognized key IDs are throttled to prevent cache-busting denial of service attacks.
5. Exact Audience Matching: Normalizes hostnames while preventing prefix and suffix spoofing (notes.com.evil.com is strictly rejected).

---

Getting Started#

The package is available on PyPI and GitHub:

• PyPI: agentonboard-sdk
• GitHub: agentonboard/agentonboard-python-sdk
• Documentation: Check out the Python (FastAPI) Guide to wire your endpoints in under 5 minutes.