Skip to content

Python SDK Reference

Complete API reference for the capiscio-sdk Python package.

Auto-Generated Documentation

This reference is automatically generated from the SDK source code docstrings. It is always accurate and up-to-date with the installed SDK version.

Installation

pip install capiscio-sdk

Requirements: Python ≥3.10

Quick Import Reference

# Core security class
from capiscio_sdk import SimpleGuard

# Executor wrapper and decorators
from capiscio_sdk import CapiscioSecurityExecutor, secure, secure_agent

# Configuration
from capiscio_sdk import SecurityConfig, DownstreamConfig, UpstreamConfig

# Errors
from capiscio_sdk.errors import (
    ConfigurationError,
    VerificationError,
    CapiscioSecurityError,
    CapiscioValidationError,
    CapiscioSignatureError,
    CapiscioRateLimitError,
)

# Types
from capiscio_sdk import ValidationResult, ValidationIssue, ValidationSeverity

API Reference

  • SimpleGuard

    Zero-config security middleware. Convention-over-configuration for signing and verifying A2A messages.

    SimpleGuard API

  • SecurityConfig

    Configuration classes for downstream protection, upstream validation, and security presets.

    Configuration API

  • CapiscioSecurityExecutor

    Full-featured security wrapper for production agents using the A2A SDK. Includes secure() and secure_agent() decorators.

    Executor API

  • Errors

    Exception classes for security errors, validation failures, signature issues, and rate limiting.

    Errors API

  • Types

    Data types for validation results, issues, and severity levels.

    Types API

File Structure Convention

SimpleGuard uses convention-over-configuration. It expects this directory structure:

your-project/
├── agent-card.json          # Your agent's identity card
└── capiscio_keys/
    ├── private.pem          # Ed25519 private key
    ├── public.pem           # Ed25519 public key  
    └── trusted/             # Trust store directory
        ├── {kid1}.pem       # Trusted public key (filename = key ID)
        └── {kid2}.pem       # Another trusted key

In dev_mode=True, SimpleGuard auto-generates all missing files.

Header Convention

Header Description
X-Capiscio-JWS JWS token from make_headers()
Authorization: Bearer <jws> Alternative header format

Constants

Constant Value Description
MAX_TOKEN_AGE 60 seconds Token expiration time
CLOCK_SKEW_LEEWAY 5 seconds Allowed clock drift

See Also