Python SDK

pip install parmana

pip install "parmana[verify]"

pip install -e ./python

from parmana import ParmanaClient

client = ParmanaClient(
    endpoint="http://localhost:3000",
    api_key="my-secret-api-key",
)

health = client.execution.health()  # GET /health, no key required

from parmana import ConflictError, NotFoundError, ValidationError

try:
    client.execution.execute(transaction)
except ConflictError as exc:          # HTTP 409
    print(exc.status_code, exc)

client.execution.execute(transaction)             # POST /execute
client.execution.health()                         # GET /health
client.execution.version()                        # GET /version (the server's version)
client.verification.verify(id)                    # POST /verify        (fresh)
client.verification.get_latest(id)                # GET /verification/:id (cached)
client.receipt.generate(id)                       # POST /receipt
client.receipt.get_latest(id)                     # GET /receipt/latest/:id
client.replay.replay(id)                          # POST /replay
client.transactions.create(transaction)           # POST /transactions
client.transactions.get(id)                       # GET /transactions/:id
client.transactions.list()                        # GET /transactions
client.trust_records.get(id)                      # GET /trust-records/:id
client.trust_records.list()                       # GET /trust-records           (1.3.0)
client.refusal.get(id)                            # GET /refusal/:id
client.refusal.verify(record)                     # POST /refusal/verify
client.audit.verify(event, signature)             # POST /audit/verify
client.execution_intents.get(id)                  # GET /execution-intents/:id
client.execution_intents.verify(intent)           # POST /execution-intents/verify
client.execution_intents.list_unfinalized()       # GET /execution-intents/unfinalized
client.execution_intents.finalize(id)             # POST /execution-intents/:id/finalize
client.execution_intents.resolve(id, resolution=..., note=...)  # POST /execution-intents/:id/resolve
client.policy.validate(policy_id, policy_version) # POST /policies/validate
client.policy.propose_change(name, version, proposed_content=..., reason=...)  # (1.3.0)
client.policy.list_changes(status)                # GET /policies/pending-changes (1.3.0)
client.policy.approve_change(id, step_up)         # POST .../approve             (1.3.0)
client.policy.reject_change(id, reason, step_up)  # POST .../reject              (1.3.0)
client.callers.me()                               # GET /callers/me              (1.3.0)
client.callers.public_key(key_id)                 # GET /keys/:keyId             (1.3.0)

from parmana import ParmanaClient, PolicyReference, create_business_transaction

client = ParmanaClient(endpoint=endpoint)

transaction = create_business_transaction(
    principal_id="alice@example.com",  # must match your key's allowed_principal_ids
    purpose="Vendor payment approval",
    action="test:fixture-execute",  # a test capability, registered only with NODE_ENV=test
    target="vendor/vendor-123",
    parameters={"amount": 100, "currency": "USD"},
    policy=PolicyReference(name="vendor-payment", version="2.1.0", schema_version="1.0.0"),
    signals={
        # The approver's signed approval for this target, up to this amount
        # (parmana.crypto.sign_approval). Without it the request is refused.
        "humanApproved": True,
        "approvalArtifact": approval,
        "vendorVerified": True,
        "invoiceVerified": True,
        "paymentApproved": True,
        "sufficientFunds": True,
        "paymentAmount": 100,
        "riskScore": 5,
        "vendorId": "vendor/vendor-123",  # boundSignals: SignalIntentBinder rejects this
        # request unless this exactly equals `target` above
    },
)

trust_record = client.execution.execute(transaction)

in_effect = client.policy_in_effect("paytm:refund")

in_effect.policy.version          # "1.2.0"
in_effect.policy.schema_version   # "1.0.0"
in_effect.signals.facts           # ["fraudCheckPassed", "managerApproved", "refundAmount", "refundEligible"]
in_effect.signals.bound           # {"refundAmount": "parameters.amount"}
in_effect.signals.approval        # {"managerApproved": {"resourceId": "parameters.orderId", "value": "parameters.amount"}}

change = maker.external_connectors.propose_register(
    capability="erp:create-invoice",
    endpoint_url="https://erp.example.com/parmana/release",
    policy="erp-invoice",
    allowed_parameters=["amount", "currency"],
    reason="Finance creates invoices in the ERP through Parmana.",
)

checker.approve_external_connector_change(
    change.change_id,
    sign_policy_change_step_up(
        pending_policy_change_id=change.change_id,
        action="approve",
        private_key_pem=Path("step-up.private.pem").read_text(),
        key_id="checker-step-up-1",
    ),
)

checker.list_external_connectors()  # [ExternalConnector(capability="erp:create-invoice", status="active", ...)]

from pathlib import Path
from parmana.crypto import sign_approval

approval = sign_approval(
    private_key_pem=Path("manager-priya__manager-priya-key-1.private.pem").read_text(),
    approver_id="manager-priya",
    key_id="manager-priya-key-1",
    capability="paytm:refund",
    resource_id="ORD-1042",
    max_amount=75000,  # leave out when the policy declares no amount
)

# The agent sends it in signals["approvalArtifact"] on a new request.

from parmana.crypto import sign_policy_change_step_up

# The proposer
change = proposer.approvers.propose_add(
    approver_id="manager-priya",
    key_id="manager-priya-key-1",
    public_key_pem=public_key_pem,  # the approver's .public.pem file
    reason="Priya approves refunds for the West region from October.",
)

# A different person, the checker
pending = checker.approver_changes("PENDING_APPROVAL")
checker.approve_approver_change(
    change.change_id,
    sign_policy_change_step_up(
        pending_policy_change_id=change.change_id,
        action="approve",
        private_key_pem=checker_step_up_key_pem,
        key_id="checker-step-up-1",
    ),
)

approvers = checker.list_approvers()

from parmana import ParmanaClient

client = ParmanaClient(endpoint="http://127.0.0.1:3000", api_key="pk_local_...")

me = client.caller()
# CallerIdentity(caller_id='local-operator', allowed_principal_ids=['local-operator'],
#                allowed_capabilities=['paytm:refund'], unrestricted_capabilities=False)

key = client.public_key("default")
# key.pem is the SPKI PEM that signs Trust Records, Refusal Records and Execution Intents

from parmana import ParmanaClient
from parmana.crypto import verify_execution_intent_offline, verify_execution_trust_record_offline

client = ParmanaClient(endpoint="http://127.0.0.1:3000", api_key="pk_local_...")
pem = client.public_key("default").pem

record = client.trust_record("5015499d-b7ba-48fe-a9ad-821862d70ad0")
result = verify_execution_trust_record_offline(record, {"default": pem})
# OfflineVerificationResult(valid=True, hash_valid=True, legacy_signature_valid=True, ...)

view = client.execution_intent("5015499d-b7ba-48fe-a9ad-821862d70ad0")
verify_execution_intent_offline(view.intent, {"default": pem})

from parmana.crypto import verify_parmana_release

result = verify_parmana_release(
    body,
    public_keys={"default": pem},  # client.public_key("default").pem
    audience="https://erp.example.com/parmana/release",  # this endpoint, as registered
    is_already_executed=lambda business_transaction_id: business_transaction_id in answers,
)

if not result.valid:
    ...  # Act on nothing. result.errors says why.
elif result.already_executed:
    ...  # Answer with the first result again; do not act twice.
else:
    ...  # Act on result.release["capability"], ["target"] and ["parameters"] only.

import json
from pathlib import Path

from parmana import ParmanaClient
from parmana.crypto import sign_policy_change_step_up

endpoint = "http://127.0.0.1:3000"
proposer = ParmanaClient(endpoint=endpoint, api_key="pk_local_... (alice)")
approver = ParmanaClient(endpoint=endpoint, api_key="pk_local_... (bob)")

change = proposer.propose_policy_change(
    "customer-refund",
    "1.0.0",
    proposed_content=json.loads(Path("policies/customer-refund/1.2.0/policy.json").read_text()),
    reason="Adopt the shipped customer-refund policy.",
)

open_changes = approver.policy_changes("PENDING_APPROVAL")
# each entry has diff.current and diff.proposed

step_up = sign_policy_change_step_up(
    pending_policy_change_id=change.pending_policy_change_id,
    action="approve",
    private_key_pem=Path("approver/step-up.private.pem").read_text(),
    key_id="bob",
)

approved = approver.approve_policy_change(change.pending_policy_change_id, step_up)
# approved.status is PendingPolicyChangeStatus.APPROVED

from parmana import ParmanaClient

client = ParmanaClient(endpoint="http://127.0.0.1:3000", api_key="pk_local_...")

records = client.trust_records.list(page=1, page_size=25, since="2026-09-01T00:00:00Z")
receipt = client.latest_receipt("5015499d-b7ba-48fe-a9ad-821862d70ad0")