Integrate the SDK in Your Workloads

Install the SDK

pip install git+https://github.com/authsec-ai/sdk-authsec.git#subdirectory=packages/python-sdk

Or add to your requirements.txt:

git+https://github.com/authsec-ai/sdk-authsec.git#subdirectory=packages/python-sdk

---

Use the SDK in Your Code

Minimal example — mTLS server with JWT-SVID validation:

import os, asyncio, ssl
from fastapi import FastAPI, Request, HTTPException
import uvicorn
from AuthSec_SDK import QuickStartSVID

app = FastAPI()
svid = None


@app.on_event("startup")
async def startup():
    global svid
    # One line — fetches X.509 SVID, starts auto-renewal
    svid = await QuickStartSVID.initialize(
        socket_path=os.getenv("SPIFFE_ENDPOINT_SOCKET", "/run/spire/sockets/agent.sock")
    )
    print(f"Identity: {svid.spiffe_id}")
    # spiffe://YOUR-TENANT-UUID/agent/.../workload-name


@app.get("/health")
async def health():
    return {"status": "ok", "spiffe_id": svid.spiffe_id}


@app.post("/protected")
async def protected(request: Request):
    # Validate caller's JWT-SVID
    auth = request.headers.get("authorization", "")
    if not auth.startswith("Bearer "):
        raise HTTPException(401, "JWT-SVID required")

    result = await svid.validate_jwt_svid(auth.split(" ")[1], audience="my-api")
    if not result:
        raise HTTPException(403, "Invalid JWT-SVID")

    return {
        "caller": result["spiffe_id"],
        "permissions": result["claims"].get("permissions", []),
    }


async def main():
    await startup()
    config = uvicorn.Config(
        app, host="0.0.0.0", port=8443,
        ssl_keyfile=str(svid.key_file_path),
        ssl_certfile=str(svid.cert_file_path),
        ssl_ca_certs=str(svid.ca_file_path),
        ssl_cert_reqs=ssl.CERT_REQUIRED,
    )
    await uvicorn.Server(config).serve()


if __name__ == "__main__":
    asyncio.run(main())

Calling another service over mTLS:

import httpx

ssl_ctx = svid.create_ssl_context_for_client()

async with httpx.AsyncClient(verify=ssl_ctx) as client:
    # Fetch a JWT-SVID for authorization
    token = await svid.fetch_jwt_svid(audience=["target-api"])

    resp = await client.post(
        "https://other-service:8443/protected",
        headers={"Authorization": f"Bearer {token}"},
        json={"action": "do-something"},
    )

---

Deploy Your Workload

Kubernetes

Add the agent socket volume mount and pod metadata env vars to your Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: production
spec:
  template:
    spec:
      serviceAccountName: order-service   # Must match workload entry selectors
      containers:
        - name: order-service
          image: your-registry/order-service:latest
          env:
            - name: SPIFFE_ENDPOINT_SOCKET
              value: "/run/spire/sockets/agent.sock"
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: POD_UID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
            - name: SERVICE_ACCOUNT
              valueFrom:
                fieldRef:
                  fieldPath: spec.serviceAccountName
            - name: POD_LABEL_APP
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app']
          volumeMounts:
            - name: spire-agent-socket
              mountPath: /run/spire/sockets
              readOnly: true
      volumes:
        - name: spire-agent-socket
          hostPath:
            path: /run/spire/sockets
            type: Directory

Verify:

kubectl logs -n production deployment/order-service --tail=20

Docker

Your workload container mounts the shared socket volume (as shown in Deploy the Spire Agent). Build and run:

FROM python:3.11-slim

RUN apt-get update && apt-get install -y --no-install-recommends git gcc \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "main.py"]

docker compose up -d my-ai-agent
docker compose logs my-ai-agent --tail=20

Unix (VM / Bare Metal)

Set the socket path as an environment variable and run your application:

export SPIFFE_ENDPOINT_SOCKET="/run/spire/sockets/agent.sock"
python main.py

Or create a systemd service for your workload:

sudo tee /etc/systemd/system/my-ai-agent.service > /dev/null <<'EOF'
[Unit]
Description=My AI Agent
After=spire-agent.service
Requires=spire-agent.service

[Service]
Type=simple
User=myapp
Environment=SPIFFE_ENDPOINT_SOCKET=/run/spire/sockets/agent.sock
ExecStart=/opt/my-agent/venv/bin/python /opt/my-agent/main.py
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now my-ai-agent

Verify:

sudo journalctl -u my-ai-agent --tail=20

Expected output (all environments):

SVID initialized: spiffe://YOUR-TENANT-UUID/agent/.../order-service
Certificates ready:
  Cert: /tmp/spiffe-certs/svid.crt
  Key: /tmp/spiffe-certs/svid.key
  CA: /tmp/spiffe-certs/ca.crt
Automatic certificate renewal enabled