Python SDK Reference
Complete API reference for the CoreSDK Python package.
Python SDK Reference
pip install coresdk # base
pip install "coresdk[fastapi]" # FastAPI middleware
pip install "coresdk[flask]" # Flask middleware
pip install "coresdk[django]" # Django middleware
pip install "coresdk[fastapi,flask,django]" # all frameworksPython 3.10+ required.
SDKConfig
Configuration for CoreSDKClient. Reads from constructor args or env vars.
from coresdk import SDKConfig
config = SDKConfig(
sidecar_addr = "[::1]:50051", # CORESDK_SIDECAR_ADDR
tenant_id = "acme-corp", # CORESDK_TENANT_ID
service_name = "my-api", # CORESDK_SERVICE_NAME
fail_mode = "open", # CORESDK_FAIL_MODE: "open" | "closed"
dev_mode = False, # CORESDK_DEV_MODE
)
# Or load entirely from environment variables:
config = SDKConfig.from_env()| Field | Env var | Default | Description |
|---|---|---|---|
sidecar_addr | CORESDK_SIDECAR_ADDR | [::1]:50051 | Sidecar gRPC address |
tenant_id | CORESDK_TENANT_ID | acme-corp | Default tenant |
service_name | CORESDK_SERVICE_NAME | "" | OTel service name |
fail_mode | CORESDK_FAIL_MODE | open | open = allow on error · closed = deny |
dev_mode | CORESDK_DEV_MODE | False | Skip TLS verification in dev |
CoreSDKClient
Main SDK client. Wraps the sidecar gRPC connection.
from coresdk import CoreSDKClient, SDKConfig
_sdk = CoreSDKClient(SDKConfig(
sidecar_addr="[::1]:50051",
tenant_id="acme-corp",
fail_mode="open",
)).validate_token(token, *, action="", resource="") → AuthDecision
Validates a JWT via the sidecar. Returns an AuthDecision.
decision = _sdk.validate_token("Bearer eyJ...")
if decision.allowed:
claims = decision.claims # dict: sub, tenant_id, roles, ...In fail_mode="open", if the sidecar is unreachable, returns AuthDecision(allowed=True, claims=None, reason="fail-open").
.evaluate_policy(rule, input_data) → bool
Evaluates a Rego rule. Returns True if the rule allows, False if denied.
allowed = _sdk.evaluate_policy("data.authz.allow", {
"tenant_id": "acme-corp",
"subject": "alice",
"action": "read",
"resource": "documents/doc-1",
"resource_owner": "alice",
"context": {"roles": ["viewer"]},
})Load a Rego bundle via CORESDK_POLICY_DIR=./policy.
AuthDecision
Returned by CoreSDKClient.validate_token().
from coresdk import AuthDecision
decision: AuthDecision
decision.allowed # bool
decision.claims # dict | None — JWT claims if verified
decision.reason # str | None — "fail-open", "token-rejected", etc.CoreSDKMiddleware (FastAPI)
ASGI middleware. Validates JWT on every request, stores claims on request.state.coresdk_user.
from coresdk.middleware.fastapi import CoreSDKMiddleware
class SDKAdapter:
config = _sdk.config
def authorize_sync(self, token, **kw):
return _sdk.validate_token(token, **kw)
app.add_middleware(
CoreSDKMiddleware,
sdk=SDKAdapter(),
exclude_paths=["/healthz", "/docs", "/openapi.json"],
)Claims location after middleware runs: request.state.coresdk_user (dict or None on fail-open).
CoreSDKFlask
Flask extension. Registers before_request hook and ProblemDetailError handler.
from coresdk.middleware.flask import CoreSDKFlask
CoreSDKFlask(_sdk, app)
# or deferred init:
ext = CoreSDKFlask(_sdk)
ext.init_app(app)Claims location after middleware runs: flask.g.claims (dict or None).
require_auth decorator
from coresdk.middleware.flask import require_auth
@app.get("/protected")
@require_auth
def protected():
return g.claimsRaises 403 if g.claims is None.
CoreSDKMiddleware (Django)
Django middleware. Add to MIDDLEWARE in settings.py.
# settings.py
MIDDLEWARE = ["coresdk.django.CoreSDKMiddleware", ...]
CORESDK = {
"sidecar_addr": "[::1]:50051",
"tenant_id": "acme-corp",
"fail_mode": "open",
}Claims location after middleware runs: request.coresdk_claims (dict or None).
@trace
OTel tracing decorator. Creates a span for the decorated function. Works on sync and async functions.
from coresdk.tracing.decorator import trace
@app.get("/products")
@trace(intent="list-products") # span named "list-products"
async def list_products(request: Request):
...The sidecar's PIIMaskingSpanProcessor strips emails, tokens, and API keys from span attributes before export. Nothing sensitive reaches your collector.
ProblemDetailError
RFC 9457 error. Raised by the middleware on auth failures; can also be raised from your own code.
from coresdk.errors._rfc9457 import ProblemDetailError
exc = ProblemDetailError(
type="https://coresdk.io/errors/forbidden",
title="Forbidden",
status=403,
detail="Role 'admin' required",
)
exc.to_dict() # → {"type": ..., "title": ..., "status": 403, "detail": ...}
exc.status # → 403Register the FastAPI exception handler:
from fastapi.responses import JSONResponse
@app.exception_handler(ProblemDetailError)
async def problem_detail_handler(request, exc):
return JSONResponse(status_code=exc.status, content=exc.to_dict(),
media_type="application/problem+json")Claims shape
Claims decoded from a valid JWT:
{
"sub": "alice",
"tenant_id": "acme-corp",
"roles": ["viewer", "editor"],
"email": "alice@acme.com",
"exp": 1234567890
}Custom claims added by your IdP are included as-is.
Framework claims table
| Framework | Claims location |
|---|---|
| FastAPI | request.state.coresdk_user |
| Flask | flask.g.claims |
| Django | request.coresdk_claims |