Docs

Quickstart, the live API reference, and SDK usage. Every command below was run locally against this repo before being written down here.

Quickstart

1. Boot the stack

Zero-config route, for looking around (seeded demo users, file-backed ledger, no Postgres):

docker compose --profile local-demo up local-demo

Real production boot (Postgres-backed, `PRODUCTION` mode):

export ACTASEAL_SIGNING_KEY=$(openssl rand -hex 32)
export ACTASEAL_ADMIN_USERNAME=admin
export ACTASEAL_ADMIN_PASSWORD='choose-a-real-password'
docker compose up --build

The production route boots with no policy pack bound -- /gateway/preflight returns MISSING_POLICY_REFERENCE until you load one via the config-file route (see README-DEPLOY.md in the repo for the full path, including the Postgres buildx-version prerequisite).

2. First-run setup

Open http://localhost:8000 and log in with the admin credentials above (env-var route) or through OIDC (config-file route). GET /readyz returning {"status":"ready"} means the process, ledger, and signing key are healthy -- it does not by itself mean a policy is bound.

3. First receipt

With a policy bound, POST /gateway/preflight mints a signed receipt on every decision. A runnable end-to-end example, including a real signed receipt with a bound terms_hash, is included with every deployment.

4. Verify offline

actaseal verify-receipt --receipt receipt.json --ledger ledger.json

Or, with no ActaSeal installation at all -- only the public key and the standalone verifier -- use verify.actaseal.com.

API reference

Generated directly from the live FastAPI app's own OpenAPI schema (never hand-written, so it cannot drift from the real routes) -- full API reference.

SDKs

Python

from actaseal.sdk.thin_client import ActaSeal

guard = ActaSeal("https://gateway.example.com", api_key="...", policy_id="refunds_policy")
decision = guard.guard({"action_type": "refund_request", "money": {"amount": "50.00", "currency": "USD"}})

TypeScript

The TypeScript SDK is not published to npm yet. It is installed from a tarball we provide, not with npm install. The import line below is what the API looks like once it resolves, not something you can run today. Ask and we will send you a tarball.

import { ActaSeal, ActaSealBlocked, ActaSealApprovalRequired } from "@actaseal/sdk";

const guard = new ActaSeal("https://gateway.example.com", { apiKey: process.env.ACTASEAL_API_KEY! });
const sendRefund = guard.wrap(
  (amount) => fetch("/internal/refund", { method: "POST", body: amount }),
  (amount) => ({ action_type: "refund_request", money: { amount, currency: "USD" } }),
);

LangChain / LangGraph

from actaseal.sdk.integrations.langchain_tools import guard_langchain_tool

guarded_tool = guard_langchain_tool(actaseal, my_refund_tool, action_type="refund_request")
# BLOCK -> langchain_core.tools.ToolException (surfaced to the model as a tool error)
# APPROVAL_REQUIRED -> ActaSealApprovalRequired re-raised for your own retry/escalation logic

OpenAI Agents SDK

from actaseal.sdk.integrations.openai_agents_tools import guard_openai_agents_tool

guarded_tool = guard_openai_agents_tool(actaseal, my_refund_tool, action_type="refund_request")

Both adapters are optional imports -- actaseal imports cleanly with neither framework installed.