> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usezentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Control Plane

> How Zentra governs reviewed APIs, enforces tenant policies, and secures operational evidence.

Zentra functions as a **financial infrastructure control plane**. Rather than hiding our operations behind black-box facades, Zentra makes each transaction inspectable. When your application triggers an API request, Zentra validates tenant-scoped policy rules, routes the request through verified primitives, logs deterministic ledger entries, and delivers signed, signature-verifiable webhooks.

This control plane serves as the single source of truth for engineering, compliance, finance, and operations teams to inspect state transitions, retry attempts, and raw evidence.

## Core Architectural Boundaries

The control plane isolates and governs our financial operations across four critical layers:

<CardGroup cols={2}>
  <Card title="Reviewed API Contracts" icon="file-signature">
    The reviewed public API surface represents stable contracts. Only these namespaces are guaranteed to maintain backward compatibility under production traffic.
  </Card>

  <Card title="Tenant-Scoped Isolation" icon="server">
    API keys, webhook endpoints, fee models, daily transaction velocity, and risk parameters are structurally isolated per tenant to prevent cross-contamination.
  </Card>

  <Card title="Deterministic Ledger writes" icon="book">
    No money moves without a matching ledger mutation. Ledger entries use strict idempotency keys to ensure duplicate submissions are rejected safely.
  </Card>

  <Card title="Operational Evidence Logs" icon="scroll">
    API request signatures, provider callbacks, timing logs, and compliance verifications are packed and stored as permanent audit trails.
  </Card>
</CardGroup>

## The Operational Request Path

The following diagram illustrates how an API invocation moves through Zentra's gatekeeping layers, policy engines, and evidence loggers before communicating with underlying bank or scheme partners.

```mermaid theme={null}
flowchart TB
    App["Your Application"] -->|"REST Request (sk_live_...)"| Gateway["Zentra API Gateway"]
    
    subgraph Gatekeeping["Zentra Gatekeeping Layer"]
        Gateway -->|"Validate Credentials"| Auth["API Key & Tenant Scope"]
        Auth -->|"Enforce Limits"| Policy["Tenant Policy & Routing Rules"]
    end
    
    subgraph Execution["Deterministic Core"]
        Policy -->|"Verify Idempotency"| Idem["Ledger Check (Lock Key)"]
        Idem -->|"Execute Primitive"| Core["Reviewed Core Engine"]
    end
    
    subgraph Evidence["Evidence & Operations"]
        Core -->|"Write Journal"| Ledger["Ledger Journal (immutable)"]
        Core -->|"Deliver Signed Event"| Webhooks["Signed Webhooks (automatic retry)"]
        Core -->|"Pack Metadata"| Audit["Operational Evidence Trail"]
    end
    
    Ledger -->|"Reconcile"| Bank["Bank Rail Providers"]
    Webhooks -->|"Event Callback"| App
    
    classDef app fill:#14161A,stroke:#2A2E35,stroke-width:1px,color:#F5F4F0
    classDef zentra fill:#2563FF,stroke:#AFC8FF,stroke-width:1px,color:#F5F4F0
    classDef proof fill:#2A2E35,stroke:#5770A0,stroke-width:1px,color:#F5F4F0
    
    class App,Bank app
    class Gateway,Auth,Policy,Idem zentra
    class Core,Ledger,Webhooks,Audit proof
```

## Scoped Key Verification

API keys enforce namespace restrictions at the gateway boundary. A tenant can generate multiple sandbox or live secret keys with specific permissions to protect their environment:

* **Sandbox Keys** (`sk_sandbox_...`): Restricted to virtualized bank rails and mock responses. Perfect for local integration tests and CI pipeline verification.
* **Live Keys** (`sk_live_...`): Bind to production funds. Live keys require active tenant policies and compliance approval before the gateway starts passing real transactions.
* **Granular Scopes**: Create separate keys for analytics ingestion (GET only) and card operations to isolate risk surfaces.

<Info>
  If a route or endpoint is marked `draft` or `reference` in our documentation, it exists as a design reference. Do not route live traffic through these namespaces. Always design production flows around Zentra's stable, reviewed primitives.
</Info>