SYEN Audit Integration Guide

1. OVERVIEW

SYEN Audit is a cryptographic audit ledger for AI decision systems. It records every AI action, human approval, and automated decision as a tamper-evident entry that is independently verifiable by auditors, regulators, and courts.

This guide covers installation, authentication, event ingestion, chain verification, and proof retrieval. A complete integration for a new event type takes under 30 minutes.

2. PREREQUISITES

• Python 3.10 or higher
• A running SYEN Audit deployment via AWS or Azure Marketplace
• Your tenant credentials provided at subscription activation
• Network access to your SYEN Audit endpoint

3. INSTALLATION

No custom SDK required. Use the standard Python requests library:

pip install requests

4. AUTHENTICATION

Authenticate with the API to receive a Bearer token. All subsequent requests use this token.

curl

curl -X POST https://api.syensystems.com/api/v1/attest \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "your-tenant-id",
    "agent_id": "your-agent-name",
    "agent_code_hash": "sha256-hash-of-your-agent-code"
  }'

# Returns: {"token": "Bearer ..."}

Python

import requests

resp = requests.post(
    "https://api.syensystems.com/api/v1/attest",
    json={
        "tenant_id": "your-tenant-id",
        "agent_id": "your-agent-name",
        "agent_code_hash": "sha256-hash-of-your-agent-code"
    }
)
token = resp.json()["token"]
headers = {"Authorization": f"Bearer {token}"}

5. INGESTING EVENTS

Every AI action, decision, or system event is recorded with a single ingest() call. The event_class determines the category. event_type is a free-form string scoped within the class.

Basic Event

receipt = requests.post(
    "https://api.syensystems.com/api/v1/events",
    headers=headers,
    json={
        "event_class": "EXECUTION",
        "event_type": "credit.decision.made",
        "stream_id": "your-tenant-id:prod-us-east-1:credit-decisions",
        "payload": {
            "applicant_id": "app-991",
            "decision": "APPROVED",
            "score": 740
        }
    }
).json()

print(receipt["event_id"])          # Unique event identifier
print(receipt["sequence_counter"])  # Position in the chain

Event with Human Decision Surface

When a human reviewed and approved a decision, include the decision_surface to record what was shown, when, and what they decided.

receipt = requests.post(
    "https://api.syensystems.com/api/v1/events",
    headers=headers,
    json={
        "event_class": "EXECUTION",
        "event_type": "credit.decision.made",
        "stream_id": "your-tenant-id:prod-us-east-1:credit-decisions",
        "payload": {"applicant_id": "app-991", "decision": "APPROVED"},
        "decision_surface": {
            "explainability_artifact_hash": "sha256-of-artifact-shown",
            "human_decision": "APPROVE",
            "presentation_timestamp": "2026-03-20T14:00:00Z",
            "signoff_timestamp": "2026-03-20T14:00:03Z",
            "decision_complexity_tier": 2
        }
    }
).json()

# True if signoff was under the threshold for the complexity tier
print(receipt["velocity_flag_triggered"])

Event with Extended Context

Pass optional context fields to capture AI model provenance, infrastructure details, and compliance gate results.

receipt = requests.post(
    "https://api.syensystems.com/api/v1/events",
    headers=headers,
    json={
        "event_class": "EXECUTION",
        "event_type": "model.inference",
        "stream_id": "your-tenant-id:prod-us-east-1:model-runs",
        "payload": {"output": "APPROVED"},
        "context": {
            "trace_id": "abc-123",
            "model_version": "risk-engine-v2.1.0",
            "compliance_gate_result": "APPROVED",
            "pii_detected": False,
            "cloud_provider": "aws",
            "cloud_region": "us-east-1"
        }
    }
).json()

Event with Full Context Objects

For governed AI decisions, pass the optional context objects to satisfy all 10 proof elements. Each object is independently optional. Pass only the objects relevant to your event type.

receipt = requests.post(
    "https://api.syensystems.com/api/v1/events",
    headers=headers,
    json={
        "event_class": "EXECUTION",
        "event_type": "credit.decision.made",
        "stream_id": "your-tenant-id:prod-us-east-1:credit-decisions",
        "payload": {"applicant_id": "app-991", "decision": "APPROVED"},
        "policy_context": {
            "policy_id": "policy-credit-v3",
            "policy_version": "3.1.0",
            "framework_name": "NIST_AI_RMF",
            "requirement_id": "GOVERN-1.2",
            "policy_effect": "ALLOW",
            "exception_approved": False
        },
        "data_lineage": {
            "data_asset_id": "dataset-credit-bureau-2026-q1",
            "data_source_system": "snowflake",
            "contains_pii": True,
            "contains_financial": True,
            "consent_basis": "contractual_necessity",
            "data_classification": "confidential"
        },
        "ai_execution_context": {
            "model_provider": "anthropic",
            "model_name": "claude-sonnet-4-6",
            "model_version": "20250514",
            "prompt_hash": "sha256-of-prompt",
            "response_hash": "sha256-of-response",
            "agent_runtime": "langchain",
            "agent_decision_type": "recommendation",
            "agent_reversibility_flag": False,
            "inference_latency_ms": 340
        },
        "guardrail_context": {
            "kill_switch_checked": True,
            "kill_switch_result": "PASS",
            "approval_gate_result": "APPROVED",
            "sandbox_executed": False,
            "risk_score": 0.12,
            "override_invoked": False
        },
        "human_review_context": {
            "human_review_required": True,
            "review_decision": "APPROVE",
            "final_approver_id": "user-analyst-007",
            "review_latency_ms": 4200,
            "reviewer_role": "credit_analyst"
        },
        "outcome_context": {
            "decision_result": "APPROVED",
            "actual_action_taken": "credit.line.issued",
            "downstream_system_notified": "oracle-ebs",
            "rollback_possible": False,
            "financial_impact_usd": 25000.00
        }
    }
).json()

6. EVENT CLASSES

SYEN Audit supports eleven event classes covering the full lifecycle of an AI-assisted workflow. EXECUTION and OUTCOME are required for initial integration.

7. VERIFYING THE CHAIN

The verify endpoint confirms the chain has not been tampered with. Run this after any bulk operation or on a schedule to confirm ongoing integrity.

result = requests.get(
    "https://api.syensystems.com/api/v1/verify",
    headers=headers,
    params={"stream_id": "your-tenant-id:prod-us-east-1:credit-decisions"}
).json()

if result["verified"]:
    print(f"Chain verified: {result['checked_count']} events")
else:
    print("Integrity failure detected. Contact sales@syensystems.com.")

8. RETRIEVING PROOF

For any event, retrieve the full non-repudiable proof package. This includes cryptographic signatures, chain linkage, and the human decision surface if present. Payload data is never returned.

event_id = receipt["event_id"]

proof = requests.get(
    f"https://api.syensystems.com/api/v1/proof/{event_id}",
    headers=headers
).json()

# Proof is available for independent verification
# Contact sales@syensystems.com for auditor verification documentation

9. EXTERNAL TIMESTAMP ANCHORING

SYEN Audit performs daily anchoring of the chain to an external FIPS-compliant trusted timestamp authority. The anchor record is retrievable via the API and independently verifiable by any authorized auditor.

anchor = requests.get(
    "https://api.syensystems.com/api/v1/anchor/2026-03-20",
    headers=headers
).json()

print(anchor["anchor_status"])      # complete
print(anchor["anchor_created_at"])

# Independent verification documentation available to
# Enterprise and Federal customers on request

10. API REFERENCE

All endpoints require a Bearer token from POST /api/v1/attest except GET /api/v1/health.

11. DECISION COMPLEXITY TIERS

When a human review is recorded, the velocity flag fires if the signoff was faster than the threshold for the tier. The event is always recorded regardless of the flag.

12. PRODUCTION DEPLOYMENT

SYEN Audit deploys on Kubernetes via Helm chart. Production deployment documentation including infrastructure requirements, KMS configuration, and security hardening guidelines is provided to customers during technical onboarding.

Contact sales@syensystems.com to begin the onboarding process. Enterprise and Federal customers receive dedicated deployment assistance.

13. CONTEXT OBJECTS

The following six context objects may be passed as optional fields on any event POST. Each object is independently optional. Fields within each object are optional unless marked required.

policy_context

data_lineage

ai_execution_context

guardrail_context

human_review_context

outcome_context

14. THE 10 PROOF ELEMENTS

SYEN Audit is designed to satisfy 10 proof requirements that regulators, auditors, and courts apply to governed AI decisions. The table below maps each requirement to the API fields that must be present to satisfy it. An integration is considered complete when all 10 elements are populated for every governed event.

15. SOURCE SYSTEM MAPPING

SYEN Audit accepts event data from any upstream system via the /api/v1/events endpoint. The mappings below show which SYEN Audit fields to populate from each source system category and which event_class to use.

Identity and Access

Source systems: Okta, SailPoint, Microsoft Entra, CyberArk, Saviynt, Prove

• agent_id: the authenticated user or service account identifier
• event_class: ACCESS for session grants, privilege escalations, access reviews
• human_review_context.final_approver_id: the identity that approved the access decision
• guardrail_context.approval_gate_result: the access decision — APPROVED or DENIED
• policy_context.policy_id: the access policy that governed the decision
• data_lineage.data_source_system: set to the identity provider name

Trigger: POST to /api/v1/events on every session grant, privilege escalation, MFA challenge result, or access review decision.

Communications and Archiving

Source systems: Global Relay, Smarsh, Mimecast, Proofpoint, Arctera

• event_class: DATA for communication capture events
• data_lineage.data_asset_id: the archived message or thread identifier
• data_lineage.data_source_system: set to the archiving platform name
• data_lineage.contains_pii: set based on the communication content classification
• payload: include communication type, channel, custodian identifiers
• policy_context.policy_id: the supervision policy that flagged or cleared the communication

Trigger: POST to /api/v1/events when a communication is flagged, escalated, placed on legal hold, or cleared by a supervision workflow.

Fraud, AML, and Investigations

Source systems: NICE Actimize, Feedzai, Sardine, Quantifind, Featurespace, Quantexa, FICO Falcon

• event_class: DETECTION for alerts fired, ANALYSIS for risk scores, OUTCOME for final case disposition
• guardrail_context.risk_score: the numeric risk score from the fraud or AML engine
• guardrail_context.approval_gate_result: the case decision — APPROVED, DENIED, ESCALATED
• human_review_context.review_decision: analyst disposition of the alert or case
• human_review_context.final_approver_id: the investigator or analyst who closed the case
• outcome_context.decision_result: final case outcome
• outcome_context.financial_impact_usd: transaction value if financially material
• ai_execution_context.model_provider: the fraud model provider
• ai_execution_context.model_name: the specific detection model

Trigger: POST on alert creation, case status change, analyst review, and final case disposition.

Data and Analytics

Source systems: Snowflake, Cloudera, Teradata

• event_class: DATA for query execution and dataset access
• data_lineage.data_asset_id: the dataset, table, or view identifier
• data_lineage.data_source_system: set to the platform name
• data_lineage.contains_pii: set based on dataset classification
• data_lineage.contains_financial: set based on dataset classification
• data_lineage.lineage_upstream_ids: upstream dataset identifiers if this dataset is derived
• data_lineage.data_classification: the data tier from your governance catalog
• payload: include query hash, row count accessed, requesting service identity

Trigger: POST on every governed dataset query, export, or transformation that feeds a downstream AI decision or compliance-relevant workflow.

AI Execution

Source systems: Azure OpenAI, AWS Bedrock, Gemini API, LangChain, LangSmith

• event_class: EXECUTION for model inference events
• ai_execution_context.model_provider: the model provider
• ai_execution_context.model_name: the specific model
• ai_execution_context.model_version: the model version string
• ai_execution_context.prompt_hash: SHA-256 hash of the prompt — do not send the prompt itself
• ai_execution_context.response_hash: SHA-256 hash of the response — do not send the response itself
• ai_execution_context.agent_runtime: the agent framework if applicable
• ai_execution_context.tool_calls_made: names of any tools the agent invoked
• ai_execution_context.retrieval_sources: source IDs used in RAG retrieval
• ai_execution_context.inference_latency_ms: latency in milliseconds
• policy_context.policy_id: the AI governance policy governing this inference

Trigger: POST on every model inference that feeds a governed business decision. Hash the prompt and response locally before sending. Never send raw prompt or response content to the SYEN Audit API.

AppSec and Code Quality

Source systems: Veracode, SonarQube, Checkmarx, Mend, DeepSource

• event_class: INTENT for policy and scan configuration changes, ANALYSIS for scan results
• agent_code_hash: SHA-256 hash of the artifact that was scanned
• policy_context.policy_id: the AppSec policy that governs this artifact
• guardrail_context.approval_gate_result: the gate decision — APPROVED, DENIED, REQUIRES_REMEDIATION
• payload: include scan tool name, finding count by severity, artifact identifier

Trigger: POST on scan completion and on gate decision — approved to deploy or blocked pending remediation.

Workflow and ITSM

Source systems: ServiceNow, PagerDuty

• event_class: RESPONSE for actions taken during incidents, INTENT for change requests
• payload: include ticket or incident identifier, assigned team, priority level
• human_review_context.final_approver_id: the approver of the change or incident action
• human_review_context.review_decision: APPROVE or REJECT
• guardrail_context.approval_gate_result: change advisory board result if applicable
• outcome_context.actual_action_taken: the specific configuration change or remediation applied
• outcome_context.downstream_system_notified: the system that received the change

Trigger: POST on change approval, incident escalation, production change execution, and incident closure.

Endpoint and Device

Source systems: CrowdStrike, Jamf Pro, Microsoft Intune

• event_class: DETECTION for endpoint threats, ACCESS for device compliance checks
• data_lineage.data_source_system: set to the endpoint platform name
• guardrail_context.risk_score: device risk score from the endpoint platform
• guardrail_context.approval_gate_result: PASS or BLOCK based on device compliance state
• payload: include device identifier, OS version, compliance policy result, detection type if applicable

Trigger: POST on device compliance check failures, threat detections, and policy enforcement actions that gate application or data access.

Finance and AP/AR

Source systems: BlackLine, SAP Ariba, Coupa, Oracle EBS, Tipalti, HighRadius

• event_class: EXECUTION for payment and approval actions, OUTCOME for final financial decisions
• outcome_context.financial_impact_usd: dollar value of the transaction
• outcome_context.actual_action_taken: the specific financial action — e.g. payment.issued, credit.line.approved, invoice.written.off
• outcome_context.downstream_system_notified: receiving system — e.g. oracle-ebs, bank-api
• human_review_context.final_approver_id: the finance approver identity
• human_review_context.review_decision: APPROVE or REJECT
• policy_context.policy_id: the financial controls policy governing this transaction
• data_lineage.data_source_system: set to the finance platform name

Trigger: POST on payment approval, write-off approval, credit decision, vendor onboarding approval, and any transaction that requires an audit trail for SOX, GAAP, or regulatory examination.