grantex-fastapi

FastAPI dependency injection for Grantex grant token verification and scope-based authorization.

Verify Grantex JWTs and enforce scopes on any FastAPI route with a single Depends().

Install

pip install grantex-fastapi

Quick Start

from fastapi import Depends, FastAPI
from grantex import VerifiedGrant
from grantex_fastapi import GrantexAuth, GrantexFastAPIError, grantex_exception_handler

app = FastAPI()
app.add_exception_handler(GrantexFastAPIError, grantex_exception_handler)

JWKS_URI = "https://api.grantex.dev/.well-known/jwks.json"
grantex = GrantexAuth(jwks_uri=JWKS_URI)

# Verify token — grant is injected automatically
@app.get("/api/calendar")
async def calendar(grant: VerifiedGrant = Depends(grantex.scopes("calendar:read"))):
    return {"principalId": grant.principal_id, "scopes": list(grant.scopes)}

How It Works

GrantexAuth is a callable class that acts as a FastAPI dependency:

1. Extracts the Bearer token from the Authorization header
2. Verifies the RS256 signature against the Grantex JWKS endpoint
3. Returns a typed VerifiedGrant object with principal, agent, scopes, and timestamps
4. The .scopes() method adds scope enforcement on top

Token Verification Only

Use Depends(grantex) to verify the token without checking scopes:

@app.get("/api/me")
async def me(grant: VerifiedGrant = Depends(grantex)):
    return {"principalId": grant.principal_id, "agentDid": grant.agent_did}

Scope Enforcement

Use Depends(grantex.scopes(...)) to verify the token AND check scopes:

# Single scope
@app.get("/api/calendar")
async def calendar(grant: VerifiedGrant = Depends(grantex.scopes("calendar:read"))):
    ...

# Multiple scopes — all required
@app.post("/api/email/send")
async def send_email(grant: VerifiedGrant = Depends(grantex.scopes("email:read", "email:send"))):
    ...

Or check scopes inside the handler:

from grantex_fastapi import require_scopes

@app.get("/api/data")
async def data(grant: VerifiedGrant = Depends(grantex)):
    require_scopes(grant, "data:read")
    ...

Custom Token Extraction

from fastapi import Request

def extract_from_cookie(request: Request) -> str | None:
    return request.cookies.get("grant_token")

grantex = GrantexAuth(jwks_uri=JWKS_URI, token_extractor=extract_from_cookie)

Custom Error Handling

Register the built-in exception handler for JSON error responses:

app.add_exception_handler(GrantexFastAPIError, grantex_exception_handler)

Or write your own:

from fastapi import Request
from fastapi.responses import JSONResponse
from grantex_fastapi import GrantexFastAPIError

@app.exception_handler(GrantexFastAPIError)
async def custom_handler(request: Request, exc: GrantexFastAPIError) -> JSONResponse:
    if exc.code == "TOKEN_EXPIRED":
        return JSONResponse(status_code=401, content={"error": "Session expired"})
    return JSONResponse(status_code=exc.status_code, content={"error": exc.code})

Error Codes

grant Object

The VerifiedGrant dataclass contains:

Requirements

• Python 3.9+
• FastAPI >= 0.115.0
• grantex >= 0.3.6

License

Apache-2.0

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com.

Authority hardening requires Python SDK 0.7.1 (current_authority), not just a valid JWT signature. Bind the audience and trusted human/agent identities, and check the issuer before every execution. This does not create human consent or automatically consume action decisions/spend caps. Existing offline defaults remain offline. Verify registry availability before installation. See the SDK execution authority guide.