Python Quickstart
Use the Nebutra Python SDK in FastAPI, Django, or any Python backend.
Python is reserved for batch / ML / specialized libraries (per ADR 2026-05-10, TS-by-Default Backend Language Policy).
For CRUD, webhooks, billing, content management, third-party API proxies — use backends/gateway/ (TypeScript + Hono). A new Python service is only acceptable when at least one applies:
- Batch / queued work that is too long for edge runtimes (>5s typical)
- ML / scientific compute that depends on the Python ecosystem (transformers, vLLM, etc.)
- Specialized libraries with no comparable TS port
This page is for consumers of nebutra-sdk from an existing Python service (FastAPI / Django). It is not an invitation to start a Python service for general-purpose work.
Prerequisites
- Python 3.11+
- A Nebutra account with an OPC license (free)
Step 1: Install the SDK
pip install nebutra-sdkOr with Poetry:
poetry add nebutra-sdkStep 2: Configure environment variables
NEBUTRA_API_KEY=nbk_live_xxxxxxxxxxxxxxxxxxxx
NEBUTRA_ORG_ID=org_xxxxxxxxxxxxxxxxxxxxStep 3: Initialize the client
import os
from nebutra import Client
nebutra = Client(
api_key=os.environ["NEBUTRA_API_KEY"],
org_id=os.environ["NEBUTRA_ORG_ID"],
)Step 4: Verify a JWT token (FastAPI)
from fastapi import HTTPException, Header
from nebutra import verify_token
import os
async def require_auth(authorization: str = Header(...)):
if not authorization.startswith("Bearer "):
raise HTTPException(status_code=401, detail="Missing token")
token = authorization.removeprefix("Bearer ")
try:
payload = verify_token(
token,
api_key=os.environ["NEBUTRA_API_KEY"],
)
except Exception:
raise HTTPException(status_code=401, detail="Invalid token")
return payload # { user_id, org_id, scopes }Step 5: Check permissions
from nebutra_client import nebutra
from fastapi import HTTPException
async def delete_project(user_id: str, project_id: str):
allowed = await nebutra.permissions.check(
user_id=user_id,
action="delete",
resource="Project",
)
if not allowed:
raise HTTPException(status_code=403, detail="Forbidden")
# proceed with deletionStep 6: Send a webhook event
from nebutra_client import nebutra
await nebutra.webhooks.send(
event_type="invoice.paid",
payload={
"invoice_id": "inv_123",
"amount": 9900,
"currency": "usd",
},
tenant_id="org_123",
)Step 7: Full FastAPI example
from fastapi import FastAPI, Depends
from src.middleware.auth import require_auth
from nebutra_client import nebutra
app = FastAPI()
@app.get("/api/projects")
async def list_projects(auth=Depends(require_auth)):
projects = await nebutra.projects.list(org_id=auth["org_id"])
return {"data": projects}Next steps
How is this guide?
Edit on GitHub
Last updated on