caronte-sdk

Python client for the Argos authorizer — handles app authentication, JWT validation, permission checking and automatic operation sync.

Installation

pip install caronte-sdk
# With FastAPI support
pip install "caronte-sdk[fastapi]"

Quick start with FastAPI

from fastapi import FastAPI, Request
from caronte.adapters.fastapi import Caronte, operation

app = FastAPI()

caronte = Caronte(
    app,
    authorizer_url="http://localhost:4000/api",
    app_id="your-app-uuid",
    secret="your-app-secret",
)


@app.get("/public")
@operation(id="public.info", level="public")
async def public_info():
    """Anyone can call this — no token needed."""
    return {"message": "Hello, world!"}


@app.get("/items")
@operation(id="items.list", level="private")
async def list_items(request: Request):
    """Requires any authenticated user (token with non-empty groups)."""
    user = request.state.user  # TokenClaims
    return {"user": user.sub, "items": []}


@app.delete("/items/{item_id}")
@operation(id="items.delete", level="protected")
async def delete_item(item_id: str, request: Request):
    """Requires a user whose group has explicit permission for items.delete."""
    return {"deleted": item_id}

Standalone client

import asyncio
from caronte import CaronteClient, OperationDescriptor

client = CaronteClient(
    authorizer_url="http://localhost:4000/api",
    app_id="your-app-uuid",
    secret="your-app-secret",
)

client.register_operation(
    OperationDescriptor(identifier="items.list", method="read", level="private")
)

async def main():
    await client.startup()

    # Validate a token from an incoming request
    claims = await client.validate_token("<bearer-token>")

    # Check whether the token has permission
    allowed = client.check_permission(claims, "items.list", "read")
    print(f"Allowed: {allowed}")

asyncio.run(main())

Operation levels

Method auto-detection

The @operation decorator infers the method from the function name:

Configuration

import os
from caronte.adapters.fastapi import Caronte

caronte = Caronte(
    app,
    authorizer_url=os.environ["AUTHORIZER_URL"],
    app_id=os.environ["APP_ID"],
    secret=os.environ["APP_SECRET"],
)