# Obligra Verify — Full Resource Hub Corpus Generated: 2026-08-20 This file is a single concatenated Markdown export of every canonical, supporting, persona-scoped, and machine-facing page in the Obligra Verify Resource Hub. Pages are ordered by their retrieval tier (Tier 1 first), then by slug. Each page begins with YAML frontmatter that includes the page's title, slug, category, retrieval tier, retrieval role, canonical flag, last-updated date, and llmTags. The full source for any page is also published as a per-page Markdown file at `https://obligra.ai/resources/.md`. Live source of truth: https://obligra.ai/resources Machine-facing index: https://obligra.ai/llms.txt Knowledge map: see `RESOURCE_HUB_KNOWLEDGE_MAP.md` in the repository. --- --- title: Quickstart slug: quickstart category: Developers retrievalTier: 1 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/quickstart canonicalUrl: "https://obligra.ai/resources/quickstart" llmTags: - llm-aligned - integration - setup-readiness - primary-llm-reference - retrieval-tier-1 --- # Quickstart _Developers_ _Most first-time Verify integrations follow the same setup path, and this Quickstart is that path. In practice, the cost of completing it is small — about a single working session for someone familiar with the customer’s deployment tooling — and the benefit is concrete: the integration moves from ‘we should look at this’ to ‘a Sandbox record exists and can be retrieved by the operational identifier our team already uses.’ The sections below walk through what to ask Verify for, what to put in place inside the customer environment, and the customer-side decisions worth making deliberately before the longer implementation guide._ ## What this guide helps you do Use this Quickstart to prepare your customer environment for Obligra Verify and complete the first setup path. You will confirm the workspace, environment, API key, network access, and backend location needed to send one retained decision record to the Verify managed platform. This guide does not replace the full implementation guide. It gets your team ready for implementation by confirming that the required access, tools, and customer-side decisions are in place. ## Setup overview The Quickstart is a six-stage journey from a brand-new Verify workspace to a verified retained decision record in Sandbox. The path below orients you to the whole journey before you start any individual step. ![Quickstart Journey. A horizontal six-stage visual orienting the reader to the entire Quickstart path. Stage 01 Create Workspace, set up the workspace and sandbox environment that will own the retained decision records. Stage 02 Generate API Key, generate an environment-scoped API key and store it in the customer secret manager. Stage 03 Install SDK, install the Verify SDK and configure the backend client. Stage 04 Capture Record, submit one test retained decision record from the backend to the Verify API. Stage 05 Retrieve Record, open the record in the Verify Console using the operational identifier the customer team will retrieve by later. Stage 06 Verify Record, run an on-demand integrity check and confirm the retained record still matches what was captured. Bottom row shows five success checkpoints that the reader can use to track progress: Workspace Ready, SDK Installed, Record Captured, Record Retrieved, Record Verified. The Quickstart uses the Direct Integration pattern for simplicity. Production deployments commonly introduce a Customer-Owned Proxy and a Capture Decision Policy ahead of the Verify API call.](/diagrams/obligra-verify-quickstart-journey.svg) * The six stages of the Quickstart with the five success checkpoints you can use to track progress. * > **Architecture note.** The Quickstart uses the Direct Integration pattern for simplicity. Production deployments commonly introduce a Customer-Owned Proxy and a Capture Decision Policy ahead of the Verify API call. The next sections cover the integration paths in more detail; for the architectural relationship itself, see > [Capture Boundary vs Proxy](/resources/capture-boundary-vs-proxy) . The basic setup path is: - Sign in to the Verify Console. - Select or create a workspace. - Create a sandbox environment. - Generate an environment-scoped API key. - Store the key in a backend secret store or environment variable. - Confirm outbound HTTPS access to the Verify API. - Install the Verify SDK or prepare a direct API call. - Submit one test retained decision record. - Open the returned recordUrl. - Verify the record in the Verify Console. The first test should use fake, redacted, or approved sample data unless your organization has already approved production data use. ## Success checkpoints Use the five checkpoints below to confirm progress as you move through the Quickstart. Each checkpoint names the specific signal you should see before continuing to the next stage. ### Checkpoint 01 — Workspace Ready Workspace and sandbox environment exist in the Verify Console, and an environment-scoped API key has been generated and stored in the customer secret manager. You can see the workspace in the Console, the sandbox environment under it, and the API key in your secret store. ### Checkpoint 02 — SDK Installed The Verify SDK is installed in the backend service that will submit records, and the SDK client has been configured to point at the sandbox environment with the environment-scoped API key. A brief health call or configuration print confirms the SDK loaded and the key is being read from the secret store rather than from source. ### Checkpoint 03 — Record Captured One test retained decision record has been submitted successfully. The Verify API returned a response with status `recorded`, a `decisionRecordId`, and a `recordUrl`. The backend service logs confirm the submission completed without retry-exhausted errors. ### Checkpoint 04 — Record Retrieved The record opens cleanly in the Verify Console. The captured input, output, workflow context, and the operational identifier your team will retrieve by later all appear as expected. The record is reachable from the `recordUrl` returned in checkpoint 03 and from a search by `workflowId` in the Console. ### Checkpoint 05 — Record Verified An on-demand verification call against the record returns a clean result. The verification state on the record matches the verification call response, and the record’s lifecycle state is consistent with the verification outcome. At this checkpoint the Quickstart is complete. ## Choose your integration path The same Verify API is reachable from several integration patterns. The recommendation depends on the goal of the integration. Most customers should start with Direct SDK in Sandbox and move to a customer-owned proxy deployment for Production. | Goal | Recommended path | | --- | --- | | Evaluate Verify | Direct SDK | | Create first Sandbox record | Direct SDK | | Validate first workflow | Direct SDK | | AWS deployment | CloudFormation | | Infrastructure-as-code | Terraform | | Production rollout | Customer-owned proxy | | Governance program | Customer-owned proxy + capture policy | | Enterprise deployment | Customer-owned proxy + capture policy | Direct SDK is the fastest path to a first Sandbox record. Customer-owned proxy is the recommended governance boundary for Production and regulated workloads. > Direct SDK is not always the Production pattern. > > > > > Direct SDK is useful for evaluation and Sandbox validation. For Production, Governance, Enterprise, or regulated workloads, customers should evaluate a customer-owned proxy so capture decisions and field retention are enforced before data leaves the customer environment. ## Most common customer journey Most customers begin with Direct SDK integration in Sandbox to prove the capture/retrieve/verify loop. Most Production deployments introduce a customer-owned proxy before rollout so the customer can enforce capture decisions and field retention before data leaves the customer environment. ```text Quickstart │ ▼ Install and Configure Verify │ ▼ Direct SDK integration in Sandbox │ ▼ First decision record │ ▼ Retrieve and verify │ ▼ Customer-owned proxy │ ▼ Production rollout ``` Use the journey above as the mental roadmap for the rest of this Quickstart. Sandbox-first validation lowers integration risk; customer-owned proxy adoption before Production lowers governance risk. ## How Verify works Verify is a system of record for AI-assisted decisions. The customer workflow is short and predictable: capture → retrieve → inspect → verify. ```text Customer Workflow │ ▼ Verify Capture │ ▼ Decision Record │ ▼ Verify Console │ ▼ Retrieve │ ▼ Inspect │ ▼ Verify ``` Understanding the lifecycle above makes the rest of the Quickstart easier to read — each setup step maps directly onto one of these stages. ## Estimated time and effort The Quickstart is short, but the total time depends on what already exists in the customer environment. **Estimated time** - 20 to 30 minutes if the workspace, environment, and API key already exist. - 45 to 60 minutes if you need to create the workspace, environment, and secret storage entry. - Longer if your organization requires firewall review, security review, or change approval before outbound API calls. **Level of effort** - Beginner to intermediate. - Requires access to the Verify Console. - Requires basic comfort with backend configuration, environment variables, package installation, and outbound HTTPS connectivity. - Does not require changing your model provider for the first test. - Does not require inbound access into your environment for the basic setup path. ## What you need from Obligra Verify Before you begin, confirm that you have access to the following: | Item | Why it is needed | | --- | --- | | Verify Console account | Used to access your workspace, environments, API keys, records, and verification results. | | Workspace access | The workspace is the customer area where environments, keys, usage, and retained decision records are managed. | | Sandbox environment | Used for test records before production rollout. | | Environment-scoped API key | Allows a backend workflow to submit selected decision context into one Verify environment. | | Verify API endpoint | The destination your backend workflow calls over HTTPS. | | Record search access | Allows your team to confirm that the retained decision record appears in the Verify Console. | ## What you need in your environment Prepare the following customer-side items: | Customer-side item | Why it is needed | | --- | --- | | Backend application, worker, API route, or job processor | The Verify SDK or API call should run server-side, not in browser or mobile client code. | | Node.js 18 or later | Required if using the Verify SDK in a Node.js environment. | | Ability to install npm packages | Required to install the Verify SDK. | | Secret manager or secure environment variable store | Used to store the API key safely outside source code. | | Outbound HTTPS access | Allows the backend service to call the Verify API. | | Safe test payload | Used to submit the first retained decision record without exposing unnecessary sensitive data. | | Stable workflow ID | Identifies the business workflow that created the AI-assisted output. | | Operational identifiers | Help users find the retained decision record later in the Verify Console. | ## Network and access requirements For the basic setup path, the customer environment only needs outbound access to the Verify API. | Requirement | Value | | --- | --- | | Protocol | HTTPS | | Port | 443 | | Direction | Outbound from customer environment to Obligra Verify | | Source | Customer backend service, worker, API route, job processor, or integration service | | Destination | Verify API endpoint | | Authentication | Environment-scoped API key | Verify does not require inbound access into the customer environment for the basic record submission path. For production use, do not call the Verify API directly from browser code or mobile application code. API keys must be used only from trusted server-side environments. ## Required customer-side decisions Before implementation, confirm these decisions: - Which workspace will own the retained decision records? - Which environment will be used first? - Where will the API key be stored? - Which backend service will submit records to Verify? - Which workflow ID will be used? - Which operational identifiers will be sent? - Will the first test use fake, redacted, or approved sample data? - Who will confirm the retained decision record in the Verify Console? - Who will approve production data use later? These decisions prevent avoidable confusion during implementation. The most common setup problems come from using the wrong environment, storing the API key in the wrong place, sending too much data, or using identifiers that are not useful for later search. ## Fast setup path If you already have a workspace, sandbox environment, and API key, the shortest path is: - Store the API key in your backend environment. - Install the Verify SDK. - Configure the Verify client. - Send one test retained decision record. - Open the recordUrl returned in the capture receipt. - Verify the record in the Verify Console. Most teams can complete this path in 20 to 30 minutes when access is already available. Already have a workspace and API key? Continue with [Implementing Verify in a Customer Workflow](/resources/implementing-verify-in-a-customer-workflow) . ## How to know the Quickstart worked Use this checklist to confirm the Quickstart is complete: - Sandbox API key created. - Capture request succeeds — the API call returns status: recorded. - decisionRecordId returned in the capture response. - Record visible in the Verify Console under the active workspace and environment. - Record opens correctly — workflowId, operational context, and model metadata are all populated. - Verification succeeds — calling verification on the captured record returns a verification result. - Activity history visible — capture, retrieval, and verification events are listed for the record. If all checks pass, onboarding is successful. If any of these checks fail, continue to the implementation guide and the troubleshooting sections before moving to Production. ## After this Quickstart The Quickstart is the start of a path, not the end. Once the five success checkpoints pass, the next four stages take the integration from a working Sandbox record to a Production deployment. > For the full adoption maturity arc — what each stage looks like, the operational signal and governance milestone that ends it, and the organizational handoffs between Builder, Platform, and Operations & Governance teams — see > [From Sandbox to Production](/resources/from-sandbox-to-production) . This page summarizes the four stages below; that page is the canonical reference for which stage an organization is in and what must be true to leave it. ![After This Quickstart. A horizontal four-stage visual showing the path from a verified Sandbox record to a Production deployment. Stage 01 Builder Sandbox, where the Quickstart leaves the customer team: a working Sandbox integration with one verified retained decision record. Stage 02 Integration Validation, where the customer team adds the rest of the workflows that will produce retained decision records and validates capture/retrieve/verify for each. Stage 03 Customer-Owned Proxy, where the customer deploys the proxy that enforces the Capture Decision Policy and the Field Retention Policy inside the customer environment before any data leaves it. Stage 04 Production Deployment, where the customer team promotes the integration to Production with environment-specific keys, runbooks, and review workflows. Bottom callout: The Quickstart is the start of a path, not the end. Production deployments commonly add the Customer-Owned Proxy ahead of Production rollout.](/diagrams/obligra-verify-after-this-quickstart.svg) * The four stages between the Quickstart you just finished and a Production deployment. * ### Stage 01 — Builder Sandbox (you are here) You have a working Sandbox integration with one verified retained decision record. The basic capture / retrieve / verify loop has been exercised end-to-end on a single workflow. ### Stage 02 — Integration Validation The customer team extends the Sandbox integration to cover the rest of the AI-assisted workflows that will produce retained decision records, and validates the capture / retrieve / verify loop for each. The implementation guide [Implementing Verify in a Customer Workflow](/resources/implementing-verify-in-a-customer-workflow) walks the customer-side workflow changes in detail. ### Stage 03 — Customer-Owned Proxy The customer team deploys the Customer-Owned Proxy that enforces the Capture Decision Policy and the Field Retention Policy inside the customer environment before any data is transmitted to Verify. This is the stage where the Direct Integration pattern used in the Quickstart is replaced with the governed pattern used in Production. For the architectural relationship between the boundary and the proxy, see [Capture Boundary vs Proxy](/resources/capture-boundary-vs-proxy) . For the policy itself, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ### Stage 04 — Production Deployment The customer team promotes the integration to Production with environment-specific API keys, operational runbooks, monitoring, and the customer-side review workflows that retrieve retained records by the business identifier the team already uses. For the architectural shape Production deployments commonly take, see [Reference Architecture on AWS](/resources/reference-architecture-aws) and [Customer Integration Patterns](/resources/customer-integration-patterns) . ## Planning for Production? Sandbox validation usually proves the basics: - API key configuration - First capture - decisionRecordId receipt - Record visibility - Retrieval - Verification Production planning usually adds: - Customer-owned proxy - Capture decision policy - Field retention policy - Environment-specific API keys - Customer-side logging controls - Operational runbooks - Review workflows > Verify is not a surveillance logger. The customer-owned proxy and capture policy determine what becomes a retained decision record and which fields are allowed to leave the customer environment. Production reference reading: - [Configuring an AI Capture Policy — capture decision policy and field retention policy for customer-owned proxy deployments.](/resources/configuring-an-ai-capture-policy) - [Customer Integration Patterns — runtime and governance pattern selection guidance.](/resources/customer-integration-patterns) - [Server-Side Capture Pattern — canonical explanation of direct vs governed server-side capture.](/resources/server-side-capture-pattern) - [Reference Architecture: AWS — customer-side deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) ## AWS customers For AWS customers, the governed capture pattern can be deployed using one of two managed deployment artifacts. Both deploy the same customer-owned capture boundary. ### CloudFormation Best for: - AWS-first teams - Console-driven deployments - Teams that want a managed AWS template path ### Terraform Best for: - Infrastructure-as-Code programs - Platform engineering teams - Repeatable multi-environment deployments ### Both deploy the same architecture ```text Customer Application │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy │ ▼ Field Retention Policy │ ▼ Verify API ``` For AWS-specific deployment reading: - [Reference Architecture: AWS — customer-side deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) - [Customer Integration Patterns — runtime and governance pattern selection guidance.](/resources/customer-integration-patterns) ## If something does not work A handful of issues account for most first-integration friction. If something is not behaving as expected, jump to the matching section in the symptom-first troubleshooting guide. - Invalid API key. - Record not visible. - Wrong environment. - Capture policy skipped record. - Wrong AWS account. - Verification unavailable. See [Troubleshooting Verify Integrations — Quick symptom lookup](/resources/troubleshooting-verify-integrations#quick-symptom-lookup) to land directly on the section matching the symptom you are seeing. ## What to read next Recommended reading order — architecture and governance first, then method-level references. **1. [Install and Configure Verify](/resources/install-and-configure-verify)** Step-by-step setup, deployment-model selection, capture payload shape, retrieval, inspection, verification, and Production readiness — the canonical first-time implementation walkthrough. **2. [Customer Integration Patterns](/resources/customer-integration-patterns)** The two architectural decisions every Verify integration makes — runtime pattern (backend, Lambda, container, queue) and governance pattern (direct vs customer-owned proxy) — with selection guidance and AWS deployment options. **3. [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy)** Required for governed deployments. Covers the capture decision policy and the field retention policy that run inside the customer-owned proxy. **4. [Server-Side Capture Pattern](/resources/server-side-capture-pattern)** Canonical explanation of direct vs governed server-side capture, the customer-owned capture boundary, and how capture policies fit into the architecture. **5. [Reference Architecture: AWS](/resources/reference-architecture-aws)** Customer-side deployment topology for AWS-hosted workflows — the AWS-specific shape the CloudFormation and Terraform deployment artifacts produce. **6. [Troubleshooting Verify Integrations](/resources/troubleshooting-verify-integrations)** Symptom-first reference for SDK, API, Terraform, CloudFormation, capture policy, and Console issues. Use this when a first capture, retrieval, or verification call is not behaving as expected. **7. [Verify SDK Reference](/resources/verify-sdk-reference)** SDK configuration, methods, request examples, response examples, errors, and retry behavior. **8. [Verify API Reference](/resources/api-reference)** Use this reference when integrating directly with the Verify API instead of the SDK. Additional references: [Implementing Verify in a Customer Workflow](/resources/implementing-verify-in-a-customer-workflow) · [Webhook Events](/resources/webhooks) . --- --- title: Record integrity and verification slug: record-integrity-and-verification category: Trust & Security retrievalTier: 1 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/record-integrity-and-verification canonicalUrl: "https://obligra.ai/resources/record-integrity-and-verification" llmTags: - llm-aligned - trust-security - verification - record-integrity - review-lifecycle - audit - compliance - canonical-integrity-reference - primary-llm-reference - retrieval-tier-1 --- # Record integrity and verification _Trust & Security_ _Reviewers arriving at a retained decision record months later need confidence that the record they are looking at is the record captured at the AI-assisted moment. Verification is the customer-visible signal that answers that question. The retained record carries an integrity reference produced at capture time; review-time verification confirms or fails against that reference and gives reviewers a clear pass or fail outcome to frame inspection. The customer team owns the review process; Verify maintains the integrity property that makes the review trustworthy._ ## Overview When an AI-assisted decision is reviewed later — often months later, and rarely by the engineer who built the workflow — the question reviewers ask is direct: is this retained decision record the record of what actually happened, and is it consistent with what was preserved at capture time? Record integrity and verification exist specifically to answer that question. In practice, the answer arrives through a customer-visible verification status and an integrity reference that reviewers use during inspection, which is the surface the customer team interacts with. The model is deliberately customer-facing. Reviewers do not need to understand how Verify preserves records internally to use verification confidently. They retrieve the record, inspect the verification status, and decide whether the record is ready for the customer’s review workflow. That separation — the customer team owns the review, Verify supplies the integrity signal — is what makes the surface usable by reviewers who arrive without prior context. ## Why this matters for GenAI workflows GenAI-assisted decisions are produced by systems that continue to change after the decision is made — model versions evolve, prompts get refined, workflows get refactored. By the time a reviewer arrives, the runtime that produced the decision is rarely the runtime that would produce it today. In practice, the customer team almost never has the original runtime to point a reviewer at. That property makes the retained record the durable surface for review — and it makes review confidence dependent on something the runtime cannot supply: an answer to whether the retained record is consistent with what was captured. Customer-visible verification supports that confidence directly, without requiring reviewers to reconstruct the workflow or audit the platform. The need is operational, not theoretical. Compliance, audit, fraud, legal, and operations reviewers look at one specific record at a time. Each reviewer needs to know that the record being inspected is the same record that was captured — and to use that knowledge as the starting point for the customer team’s own review process. The tradeoff is symmetrical: Verify supplies a verification signal scoped narrowly enough that reviewers can trust it, and broad enough that it is meaningful at the moment review actually happens. ## Verify's role Verify supports review-oriented verification through three customer-visible surfaces: verification status, the integrity reference, and the retrieval and inspection workflows in the Verify Console and API. The role is narrow on purpose — Verify supports confidence; it does not adjudicate the customer’s review. - Preserve each retained decision record exactly as it was submitted by the customer's trusted server-side runtime. - Expose a customer-visible verification status that reviewers see alongside the retained record during retrieval and inspection. - Expose a customer-visible integrity reference that supports verification-oriented review workflows. - Maintain customer-visible review history that summarizes the chronology of review activity tied to the record. - Surface verification outcomes through the Verify Console and the public retrieval API for customers whose teams need them during review. Verification supports confidence; it does not replace human review. The customer’s review workflow determines the outcome of the review itself — Verify supplies the retained record and the verification surface that the review uses as a starting point. ## Customer responsibility Customer review workflows surround verification on both sides. Before review, the customer team defines who reviews, what triggers review, and what evidence is required. After review, the customer team determines the outcome, the remediation, and any downstream consequences. ### Before review The customer team decides which AI-assisted workflows produce records, what context each record carries, and which operational identifiers will be used to retrieve records for review later. Those decisions shape what reviewers see when they arrive. ### During review Reviewers retrieve the retained record using the same business identifiers the customer team uses operationally (claimId, encounterId, transactionId, escalationId, reviewCaseId), inspect the record, observe the verification status, and incorporate verification into the customer’s own review process. The verification status is one input to a review outcome the customer team determines. ### After review The review outcome and any downstream actions — remediation, escalation, policy change, model adjustment, or workflow refinement — belong to the customer team. Verify continues to hold the retained record and supports future retrieval and inspection, but the workflow itself is customer-driven. ## Verification concepts The concepts below summarize the customer-visible verification model. They are intentionally framed for reviewers rather than implementers — the goal is to support confident review without exposing platform mechanics. | Concept | What it means | Customer consideration | | --- | --- | --- | | Verification status | Customer-visible state of verification for the retained decision record (verified, not verified, pending, or unavailable). | Use the verification status during review workflows as an input to the customer team's own review outcome. | | Integrity reference | Customer-visible reference used in verification-oriented review of the retained decision record. | Treat the integrity reference as a customer-visible review artifact, not as an implementation detail to be inspected for platform internals. | | Retained record | The preserved decision record submitted to Verify by a trusted customer runtime at capture time. | Review the retained record as the authoritative artifact when the original context matters. Authoritative customer systems remain the source of truth for downstream operational state. | | Review history | Customer-visible chronology of review activity tied to the retained record. | Use review history during operational review to understand which reviewers have already engaged with the record. | | Verification failure | The retained record could not be verified as expected at the time of inspection. | Follow the customer team's operational runbook. A verification failure is a review signal, not a final determination. | ## Review-oriented verification lifecycle The lifecycle below shows where verification fits in the customer’s review of an AI-assisted decision. Each stage is a customer-side workflow step; Verify supports the lifecycle through preservation, retrieval, and verification surfaces. ```text Customer side Verify surface ───────────── ────────────── Capture (1) Trusted customer runtime submits the retained decision record over HTTPS ──▶ Retained Decision Record │ (preserved with │ customer-attached │ operational context) ▼ Retain (2) The record is preserved with the operational context the customer attached at capture time │ ▼ Retrieve (3) Reviewer retrieves by the business ◀── Retrieval API identifier already used operationally / Verify Console (claimId, encounterId, transactionId, escalationId, reviewCaseId, ...) │ ▼ Review (4) Reviewer inspects the retained record inside the customer's review workflow │ ▼ Verify (5) Reviewer observes the customer-visible verification ◀── Verification status status and integrity reference + integrity reference + review history │ ▼ Investigate (if needed) (6) On a verification failure or other review signal, the customer team follows the operational runbook for that workflow. The customer team determines the review outcome. Verify supports the lifecycle through preservation, retrieval, and the customer-visible verification surface. ``` ## Review considerations The considerations below summarize how customer teams should think about verification inside their own review processes. None of them displace the customer’s existing review discipline — they integrate with it. - Treat verification status as one review input. It supports confidence in the retained record; it does not produce a review outcome on its own. - Pair verification with operational context. Reviewers should retrieve by stable business identifiers and use verification alongside the retrieved record. - Document the customer team's response to a verification failure. The runbook should describe escalation, downstream actions, and any timing expectations the customer team chooses to apply. - Keep review history in mind when re-reviewing a record. Multiple reviewers may have engaged with the same record across compliance, audit, fraud, legal, or operations review. - Treat customer review as the authoritative determination. The customer's own program produces outcomes — verification is a supporting artifact. - Apply the customer's existing access discipline. Reviewers see retained records and verification status through the customer team's configured access; identity remains a customer-owned program. ## Common misconceptions The misconceptions below are common during enterprise review of how verification fits into an AI-assisted workflow. Each one clarifies a boundary that the model implies but is worth surfacing explicitly. | Misconception | How to think about it | | --- | --- | | A verification status is a legal conclusion. | Verification supports review-oriented confidence in the retained record. Legal conclusions are determined by the customer team's legal review and governance program. | | A verification status is a compliance certification. | Verification is a customer-visible record-level status. Compliance posture is shaped by the customer's policies, controls, regulatory environment, and audit program. | | Verification replaces human review. | Verification supports human review by providing confidence in the retained record. The customer's review workflow continues to determine outcomes. | | An integrity reference is something reviewers should decode or inspect for platform internals. | The integrity reference is a customer-visible review artifact. Reviewers use it during verification-oriented review, not as a window into platform mechanics. | | A verification failure means the AI-assisted decision was wrong. | A verification failure is a signal about the retained record itself, not about the AI-assisted decision. Follow the customer team's runbook to investigate and determine the appropriate response. | | Verification confirms that the AI workflow behaved correctly. | Verification is about the retained record, not the workflow. Whether the workflow behaved correctly is a question the customer team's review process answers. | | Verification status changes describe runtime monitoring. | Verification reflects the state of the retained record at the time of inspection. Runtime monitoring of customer systems is a customer responsibility. | ## Related documentation Pair this guide with the following pages for the full verification and review picture: - [Security overview — the broader security model verification sits inside.](/resources/security-overview) - [Compliance approach — how retained records and verification support customer compliance review programs.](/resources/compliance-approach) - [Verification lifecycle — the conceptual stages of capture, retention, retrieval, review, and verification.](/resources/verification-lifecycle) - [Working with Decision Records — the customer-side surface that operates on the integrity guarantee.](/resources/working-with-decision-records) - [Structure of a decision record — the customer-visible record shape verification operates over.](/resources/structure-of-a-decision-record) - [Retrieval model — how retained records are located, returned, and inspected.](/resources/retrieval-model) - [Data handling and residency — what customers submit and what Verify preserves.](/resources/data-handling) --- --- title: "Reference Architecture: AWS" slug: reference-architecture-aws category: Architecture retrievalTier: 1 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/reference-architecture-aws canonicalUrl: "https://obligra.ai/resources/reference-architecture-aws" llmTags: - llm-aligned - architecture-core - primary-llm-reference - retrieval-tier-1 --- # Reference Architecture: AWS _Reference Architecture_ _Reference deployment pattern for submitting, retaining, retrieving, and verifying AI-assisted decision records on AWS._ ## 01. Summary Most enterprise organizations evaluating Verify already run a meaningful share of their AI-assisted workflows on AWS, and the architectural question that surfaces first is predictable: how does Verify fit alongside the AWS building blocks that are already in production? This reference architecture answers that question. It describes how Obligra Verify integrates with AWS-based AI-assisted workflows to preserve decision evidence after AI output affects a real workflow, using deployment shapes customer teams already know how to operate. The customer-operated environment captures the decision context at the point of execution — input, retrieved context, prompt or request structure, model execution metadata, response, validation state, and operational identifiers. The Obligra-operated verification layer receives the captured record, normalizes it into a decision record, creates the retained decision record, and supports retrieval by operational context and verification later. The architectural seam is intentional and explicit: the capture path is separated from the retained decision record layer. Customers control where and how AI-assisted workflow context is captured. Obligra operates the record, retention, retrieval, and verification services exposed through documented APIs. The tradeoff is symmetrical — customer teams own the runtime that produces the evidence, and Obligra owns the layer that retains and serves it. The pattern is designed for GenAI-assisted workflows where later review cannot depend on reconstruction from logs, traces, screenshots, tickets, or model provider histories. In practice, that constraint is what drives most customers to this architecture in the first place. ## 02. Overview Verify integrates at the workflow edge of an AI-assisted system — the point where an AI-generated or AI-assisted output becomes part of a business workflow: a clinical summary, a transaction review, a claim assessment, a risk classification, a customer response, or an operational routing decision. At that point, the output is no longer just a model response. It becomes part of a decision that may need to be reviewed later, often by someone who was not in the room when the decision was made. Traditional application logging can show that a request moved through a system. It can show that a model endpoint was called, that a response was returned, or that a workflow advanced. But logs do not reliably preserve the complete decision state — and the gap between “we logged the call” and “we preserved the decision” is precisely what customer teams discover during their first audit. Verify is designed to preserve that decision state. In the AWS reference architecture, the customer deploys the capture layer in or near the AI-assisted workflow. That capture layer submits the decision payload to Verify, and Verify handles record assembly, retention, retrieval, and verification. The operating boundary is straightforward: > Customers deploy the capture layer. Obligra operates the verification layer. This separation is what lets customer teams keep control over their source systems and workflow integration while relying on Verify for durable decision evidence. In practice, that is the architectural property most enterprise teams say they want from a record layer before they say it out loud. ## 02a. AWS shared responsibility model The Verify architecture is intentionally split into two ownership domains. Each side has clear responsibilities, and the boundary between them is the governance boundary the customer relies on. ### Customer responsibilities The customer owns: - Application - Workflow - Prompts - Responses - Operational context - Customer-owned proxy - Capture decision policy - Field retention policy - CloudFormation deployments - Terraform deployments - Secrets - Logging - Networking - IAM controls ### Obligra responsibilities Obligra owns: - Decision record creation - Retention - Retrieval - Verification - Evidence generation - Record integrity controls - Verify Console - Customer-facing APIs The customer controls what becomes a retained decision record. Obligra operates the retained decision record layer. > Verify is not a surveillance logger. The customer-owned proxy and policy are the governance boundary. ## 02b. Direct vs governed AWS deployments Verify supports two AWS deployment patterns. Both reach the same Verify API. The difference is where capture decisions and field retention are enforced. ### Direct AWS deployment ```text Customer Runtime │ ▼ Verify API │ ▼ Decision Record ``` Best for: - Evaluation - Builder onboarding - Sandbox validation - Internal testing ### Governed AWS deployment ```text Customer Runtime │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy │ ▼ Field Retention Policy │ ▼ Verify API │ ▼ Decision Record ``` Best for: - Production - Governance - Enterprise - Regulated workloads Most customers begin with direct integration in Sandbox and introduce a customer-owned proxy before Production rollout. ## 02c. Customer-owned capture boundary The customer-owned proxy is a governance component, not a transport component. It sits inside the customer AWS account and evaluates capture and field retention rules locally before any data is transmitted to Verify. Responsibilities: - Evaluate capture decisions. - Evaluate field retention. - Apply redaction to sensitive field values. - Apply truncation to bound forwarded values. - Apply neverForward controls so excluded fields never leave the customer account. - Block unauthorized fields before they leave the customer account. - Forward only approved fields to the Verify API. Capture policy evaluation occurs before data leaves the customer AWS account. Verify receives only approved fields. ## 02d. Governance flow The flow below represents the governance path through a governed AWS deployment, not the runtime path. ```text Customer Application │ ▼ Customer Runtime │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy (capture / skip) │ ▼ Field Retention Policy (allow / drop / redact / truncate) │ ▼ Verify API │ ▼ Decision Record │ ▼ Verify Console │ ▼ Verification ``` In direct AWS deployments, the customer-owned proxy and the two policy layers are not present — the customer runtime calls the Verify API directly. The downstream surfaces (decision record, Verify Console, verification) are the same in both patterns. ## 02e. Where capture policies run Two independent policy decisions run inside the customer-owned proxy in governed AWS deployments. ### Capture decision policy Answers: should this record exist? Possible outcomes: - capture - skip ### Field retention policy Answers: which fields may leave the customer environment? Possible outcomes: - allow - drop - redact - truncate - neverForward Both evaluations occur inside the customer-owned proxy before any data is transmitted to Verify. For the policy contract, file shape, evaluation order, and field retention outcomes, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## 02f. AWS deployment options AWS customers commonly deploy the customer-owned proxy using one of two managed deployment artifacts. Both implement the same architecture; the choice depends on organizational standards. ### CloudFormation Deploys: - API Gateway - Lambda proxy - Capture policy - Customer-owned capture boundary Best for: - AWS-first teams - Console-driven deployments - Teams without Terraform standards ### Terraform Deploys: - API Gateway - Lambda proxy - Capture policy - Customer-owned capture boundary Best for: - Infrastructure-as-Code programs - Platform engineering teams - Repeatable multi-environment deployments Both deploy the same architecture. Choice depends on organizational standards. ## 02g. Which AWS deployment pattern should I choose? The matrix below covers the most common scenarios. Use it to resolve runtime, governance, and deployment-artifact decisions on one page. | Goal | Recommended pattern | | --- | --- | | Evaluate Verify | Direct SDK | | First Sandbox record | Direct SDK | | Internal tool | Direct SDK | | AWS deployment | CloudFormation | | Infrastructure-as-code | Terraform | | Production application | Customer-owned proxy | | Governance program | Customer-owned proxy | | Enterprise deployment | Customer-owned proxy | | Regulated workload | Customer-owned proxy | ## 03. Why GenAI workflows need a record layer GenAI-assisted workflows are different from traditional deterministic workflows. A deterministic workflow can often be reviewed by inspecting business rules, database state, and application logs. The execution path is usually more stable and easier to reproduce. A GenAI-assisted workflow depends on more dynamic conditions. The output may be shaped by prompt templates, retrieved context, model provider behavior, model version, runtime parameters, validation logic, workflow state, and downstream human or system action. Those elements may exist in different systems and may change after execution. Weeks or months later, the same prompt may not behave the same way. Retrieved context may return different results. Model behavior may have changed. Validation rules may have been updated. Logs may have expired or been sampled. This creates a post-inference record gap. The architecture exists to close that gap by capturing the decision state at execution time and preserving it as a retained, reviewable, and verifiable decision record. ## 04. Architecture diagram The architecture should be read as a separation of responsibilities across the customer AWS account, the customer-owned capture boundary, and the Obligra Verify managed platform. The customer-operated side owns the AI-assisted workflow and the capture boundary. The Customer Runtime executes the workflow, the Customer-Owned Proxy evaluates the Capture Decision Policy and the Field Retention Policy, and only approved fields leave the customer environment. The Obligra-operated side receives the approved fields at the Verify API and preserves them in the Managed Decision Record Platform. Retention, retrieval, verification, and evidence are exposed through documented APIs and the Verify Console. ![Reference Architecture for Obligra Verify on AWS. A three-zone horizontal topology showing the customer-owned capture boundary architecture. Zone 1 Customer AWS Account on the left contains the Application and Workflow Runtime on ECS, EKS, Lambda, EC2, or App Runner; Customer Data Sources on RDS, DynamoDB, S3, and OpenSearch; and Identity and Secrets on IAM, Secrets Manager, and Parameter Store. Zone 2 Customer-Owned Capture Boundary in the middle is the hero zone and contains the Verify SDK, the Customer-Owned Proxy deployable via CloudFormation, Terraform, or customer-managed infrastructure, the Capture Decision Policy that evaluates capture or skip outcomes, the Field Retention Policy that applies allow, drop, redact, truncate, or never-forward actions, and the Approved Fields Only gate that ensures only approved data exits the customer environment. Zone 3 Obligra Verify Managed Platform on the right contains the Verify API, the Managed Decision Record Platform handling retention, retrieval, verification, and evidence, and the Verify Console used by operations, compliance, audit, legal, risk, and review teams.](/diagrams/obligra-verify-reference-architecture-aws.svg) * Customer-Owned Capture Boundary Architecture for Obligra Verify. Customers own the capture boundary, capture policy, and governance controls. Obligra operates the managed decision record platform for retention, retrieval, verification, evidence, and review. * The diagram makes three things clear: - Capture happens at the customer-owned boundary — the Customer Runtime emits decision context, the Customer-Owned Proxy enforces Capture Decision Policy and Field Retention Policy, and only approved fields leave the customer environment. - Retention, retrieval, verification, and evidence happen in the Obligra-operated Managed Decision Record Platform behind the Verify API. - Operations, compliance, audit, legal, risk, and review teams use the Verify Console to retrieve retained decision records by operational context, not by remembered prompt text. ## 05. Data flow The reference data flow follows the decision lifecycle. - 1. An AI-assisted workflow produces or uses an output. - 2. The customer-side capture layer collects the decision context at execution time. - 3. The captured payload includes the input, retrieved context, prompt, the response, model execution metadata, validation state, and operational identifiers. - 4. The capture layer submits the payload to the Verify ingestion API. - 5. Verify validates and normalizes the submission into a decision record. - 6. Verify creates the retained decision record and applies customer-facing integrity controls. - 7. The retained decision record is preserved for later review. - 8. Retrieval metadata is preserved so records can be found later by operational context. - 9. A reviewer, auditor, compliance analyst, or authorized system retrieves the record by workflow, encounter, claim, transaction, case, date range, or verification state. - 10. Verify checks integrity and returns the retained record for review. The important design point is that the record is captured when the decision occurs. The system does not wait for an audit, dispute, or investigation to reconstruct the decision later. ![End-to-End Decision Record Lifecycle for Obligra Verify. A six-stage horizontal flow showing the lifetime of a retained decision record. Stage 01 AI-Assisted Workflow executes inside the customer runtime. Stage 02 Decision Context is captured at the customer-owned capture boundary by the Verify SDK assembling input, retrieved context, output, execution metadata, and operational identifiers. Stage 03 Submitted to Verify through the customer-owned proxy after the Capture Decision Policy and Field Retention Policy approve the fields that may leave the customer environment. Stage 04 Retained Decision Record is preserved by the Obligra managed platform, indexed by operational context, with an integrity reference attached. Stage 05 Retrieved and Verified by a reviewer using the operational identifier the customer team already uses. Stage 06 Reviewed by the customer audit, compliance, legal, risk, or operations team inside the customer review program. The bottom band shows that stages 01-03 run in the customer environment, stages 04-05 run on the Obligra managed platform, and stage 06 runs in the customer review program. Bottom callout: Captured once at execution time inside the customer-owned capture boundary. Reviewed many times across the lifetime of the record by the customer review program.](/diagrams/obligra-verify-end-to-end-decision-record-lifecycle.svg) *Lifecycle view of how an AI-assisted workflow becomes a retained decision record. Verify records decision context at execution time, preserves the retained record, and supports retrieval, review, and verification later.* ## 06. Architecture steps A typical AWS-based integration follows these architecture steps. - 1. Identify the AI-assisted workflow where output affects a business process. - 2. Place the capture integration at the workflow edge, near the point where the AI-assisted output is generated or accepted. - 3. Capture the decision payload, including input, context, prompt, the response, model execution metadata, validation results, and operational identifiers. - 4. Submit the payload to the Verify ingestion endpoint over a documented API. - 5. Normalize the payload into a decision record. - 6. Apply customer-facing integrity controls so the record can be verified later. - 7. Preserve the retained decision record. - 8. Make the record retrievable by operational context. - 9. Expose retrieval and verification through authorized APIs or review interfaces. - 10. Use the retained record for audit, compliance, legal, risk, operational review, or dispute resolution. This architecture avoids making logs, traces, screenshots, or model provider histories the system of record for AI-assisted decisions. ## 07. AWS services in this guidance The AWS reference architecture uses AWS-native service patterns that are familiar to enterprise architecture, security, and platform teams. Common AWS service mappings include: - **Amazon API Gateway** for ingestion, retrieval, and verification API exposure. - **AWS Lambda** for capture processing, validation, retained decision record creation, retrieval handlers, and verification logic. - **Amazon S3 with Object Lock** for retained decision record storage where immutable or governance-mode retention is required. - **Amazon DynamoDB** for retrieval indexes, operational metadata, decision IDs, workflow IDs, verification status, and queryable lookup fields. - **AWS Key Management Service** for managed cryptographic key services that support customer-facing integrity controls. - **AWS Step Functions** where multi-step orchestration is required for ingestion, validation, retention, retrieval, and verification. - **Amazon CloudWatch** for operational metrics, service health, and platform diagnostics. - **AWS CloudTrail** for AWS API audit trails where applicable. - **AWS Identity and Access Management** for scoped access, service roles, least privilege, and separation of duties. This page is not prescribing one mandatory AWS deployment. It describes the reference pattern: capture the decision at execution time, retain the record, index it for retrieval, and support verification later. ## 08. Deployment model The recommended deployment model separates customer-operated capture from Obligra-operated verification. ### Customer-operated capture layer - Runs in or near the customer's AWS environment, application, workflow service, or integration layer. - Captures the decision context at the point where AI-assisted output affects a workflow. - Submits the captured payload to the Verify ingestion API. - Uses customer-controlled business identifiers such as encounter ID, claim ID, transaction ID, case ID, workflow ID, service name, tenant ID, or date range. ### Obligra-operated verification layer - Receives captured decision payloads. - Normalizes them into canonical decision records. - Applies customer-facing integrity controls and retention behavior. - Preserves the retained record. - Supports retrieval by operational context. - Supports record retrieval and verification later. This model reduces customer-side operational burden. Customers do not need to operate the retained record store, retrieval indexes, or verification service themselves. They are responsible for capture integration and deciding which workflow context should be submitted. Obligra is responsible for preserving the record layer. ## 09. Deployment scenarios The reference architecture applies across multiple AI-assisted workflow patterns. ### Healthcare and telehealth A telehealth platform generates an AI-assisted visit summary or intake summary. The capture layer submits the patient encounter identifier, input, retrieved clinical or operational context, generated summary, review state, model metadata, and workflow metadata to Verify. Later, a clinical operations leader, compliance team, or authorized reviewer can retrieve the retained decision record by encounter ID, workflow ID, date range, or verification state. ### Banking and financial services A financial workflow uses AI to support transaction review, fraud triage, dispute handling, or risk classification. The capture layer submits the transaction ID, account context, retrieved risk signals, generated recommendation, validation state, and escalation metadata. Later, reviewers can retrieve the decision record by transaction ID, case ID, account, workflow, date range, or review status. ### Insurance An insurance workflow uses AI to support claims intake, coverage review, underwriting assistance, or risk classification. The capture layer submits the claim ID, policy context, prior claim history, response, routing recommendation, review flag, and retention state. Later, claims, compliance, audit, legal, or risk teams can retrieve the retained record tied to the claim and verify that the record has not changed. Across all three scenarios, the architecture serves the same purpose: preserve the AI-assisted decision record at execution time so review does not depend on reconstruction later. ## 10. Network requirements Network requirements depend on the customer deployment model, but the reference pattern is straightforward. Customer workloads need an approved path to submit captured decision payloads to the Verify ingestion interface. At minimum, this usually requires: - outbound HTTPS connectivity from the customer application, workflow service, or capture layer to the Verify API endpoint; - firewall or egress policy approval for the Verify endpoint; - TLS for data in transit; - customer-side network controls that align with internal security policy; - access controls that prevent unauthorized systems from submitting decision payloads. For regulated or restricted environments, customers may require additional controls such as private connectivity patterns, egress inspection, IP allowlisting, VPC endpoint patterns, or customer-managed network approval workflows. The architecture should not require customer workloads to access the retained record store directly. Capture, retrieval, and verification should occur through documented APIs and authorized integration paths. ## 11. IAM roles and permissions IAM design should enforce least privilege and separation of duties. A reference implementation should distinguish between the following access patterns: - **Capture submitter:** application or workflow identity allowed to submit decision records. - **Retrieval user or service:** authorized role allowed to search for and retrieve records. - **Verification user or service:** authorized role allowed to request integrity verification. - **Administrative operator:** limited role used for configuration, policy, or integration management. - **Audit or compliance reviewer:** read-oriented role that can access records within approved scope. The capture layer should only receive permissions required to submit decision payloads. It should not have broad access to retained record storage or unrelated workflow records. Retrieval access should be scoped by tenant, workflow, business unit, environment, or other authorization boundaries. Verification access should also be scoped. Not every user who can submit a record should automatically be able to retrieve or verify every record. This separation supports least privilege, reduces blast radius, and gives security and compliance teams a clearer control model. ## 12. Security and data protection Security and data protection controls should be designed around the sensitivity of the AI-assisted workflow. The reference architecture should support: - encryption in transit for capture, retrieval, and verification API calls; - encryption at rest for retained decision records and retrieval indexes; - customer-facing integrity controls for retained records; - integrity verification when records are retrieved; - scoped access for capture, retrieval, verification, administration, and review; - retention controls aligned to customer policy and use case requirements; - audit trails for access, retrieval, and administrative actions; - data minimization rules for what is captured and retained; - separation between source workflow systems and retained decision record storage. Customers remain responsible for deciding which business data, clinical data, financial data, claim data, model metadata, and operational context should be captured. Verify is responsible for preserving the retained decision record according to the configured record and verification model. The goal is not to collect everything. The goal is to preserve the decision evidence needed for later review. ## 13. Cost considerations Cost considerations are driven by record volume, record size, retention duration, retrieval frequency, verification frequency, and integration pattern. Primary cost drivers may include: - number of AI-assisted decision records captured; - size of each retained record; - volume of retrieved context included in each record; - retention duration and storage class; - indexing volume and lookup patterns; - frequency of retrieval and verification requests; - orchestration complexity for ingestion, retention, retrieval, and verification; - network transfer and integration costs where applicable. Customers should size the architecture based on the workflows they intend to capture. A low-volume internal review workflow may produce smaller cost impact than a high-volume transaction, claims, or telehealth workflow. Architecture teams should evaluate expected records per day, average record payload size, retention period, retrieval patterns, and compliance requirements before production rollout. ## 14. Customer responsibility The customer is responsible for the capture boundary. That includes: - identifying which AI-assisted workflows require decision records; - integrating the capture layer into the application or workflow path; - deciding which inputs, context, outputs, model metadata, validation results, and operational identifiers should be captured; - ensuring source-system permissions are appropriate; - managing customer-side authentication, authorization, and network controls; - classifying data before capture where required; - defining retention expectations based on policy, legal, regulatory, and business requirements; - ensuring that users and systems submitting records are authorized to do so. Obligra is responsible for the Verify record layer. That includes: - receiving decision payloads through documented interfaces; - normalizing records into the supported decision record structure; - applying customer-facing integrity controls and supporting verification states; - storing retained records; - indexing records for retrieval; - supporting authorized retrieval and verification workflows; - maintaining the managed verification platform. This shared responsibility model should be reviewed during architecture, security, compliance, and procurement review. ## 15. Risk, compliance, and audit considerations This architecture is not only a storage pattern. It is a review and evidence pattern for AI-assisted workflows. For risk teams, the architecture reduces reliance on informal reconstruction when a decision is questioned. For compliance teams, it creates a retained record that can be inspected against policy. For audit teams, it creates a structured artifact that can be sampled, retrieved, and verified. For legal teams, it provides a clearer record of what was captured, when it was captured, and whether the retained record still verifies. This matters because AI-assisted decisions may be reviewed long after the model output was generated. If the organization depends only on logs, traces, screenshots, model provider histories, or human memory, the review process becomes fragile. A retained decision record creates a stronger control position. It gives the organization evidence that can be retrieved by operational context and verified later. ## 15a. How to know the architecture is working Use this checklist to confirm an AWS deployment of Verify is wired end-to-end. If every item below is true, the architecture is functioning correctly. - Capture request succeeds — the customer runtime submits the call without network or SDK errors. - HTTP 201 returned — the response status indicates the record was created. - decisionRecordId returned in the capture response in the dr_ format. - Record visible in the Verify Console under the active environment and workspace. - Retrieval works — the record can be found by decisionRecordId and by operational context. - Verification works — calling verification on the captured record returns a verification result. - Environment separation confirmed — Sandbox and Production credentials, runtimes, and downstream review surfaces are all isolated. - Capture policy behaves as expected — in governed deployments, the proxy log shows the matched rule and outcome. - Allowed fields appear — fields the field retention policy allows are present on the retained decision record. - Dropped fields do not appear — fields the field retention policy drops, redacts, truncates, or marks neverForward are not present. - Logs contain metadata only — no prompts, responses, API keys, bearer tokens, secrets, or dropped fields appear in CloudWatch or other customer-side logs. > If all checks pass, the AWS architecture is functioning correctly. Move on to a Production readiness review before connecting active production workflows. ## 15b. Common AWS deployment mistakes The mistakes below are the ones most commonly seen during first AWS deployments and during the move from Sandbox to Production. ### Calling Verify from browser code The Verify capture surface is not designed for browser-side JavaScript, mobile clients, embedded devices, or any other untrusted runtime. Use a trusted backend runtime — Lambda, ECS, EKS, or a backend service — that holds the API key inside the customer trust boundary. ### Using Production before Sandbox validation Validate the full capture loop end-to-end in Sandbox before promoting any workflow to Production. Sandbox-first validation lowers integration risk and surfaces operational-context, retrieval, and verification issues early. ### Deploying direct integration in regulated workloads Direct integration has no customer-owned capture boundary and no customer-owned policy enforcement. Regulated workloads should use a customer-owned proxy and capture policy so capture decisions and field retention are evaluated inside the customer AWS account. ### Losing operational context Preserve workflowId and business identifiers (claimId, encounterId, transactionId, ticketId, escalationId) across every component on the customer side — applications, queues, Lambdas, containers, and the customer-owned proxy. If operational context is lost, retrieval breaks downstream. ### Treating operational context as prompt content Operational context is separate from prompt and response. Stuffing identifiers into the prompt or response field is a retrieval anti-pattern — the identifiers will not be indexed as retrieval keys and reviewers will not be able to find the record using business-side identifiers. ### Treating webhook payloads as authoritative records A webhook event is a notification, not the system of record. Acting on the payload as authoritative bypasses the retrieval surface designed for that purpose. Treat webhook events as triggers and retrieve by decisionRecordId or operational context. --- --- title: What is Obligra Verify? slug: what-is-verify category: Fundamentals retrievalTier: 1 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/what-is-verify canonicalUrl: "https://obligra.ai/resources/what-is-verify" llmTags: - llm-aligned - canonical-concept - system-of-record - primary-llm-reference - retrieval-tier-1 --- # What is Obligra Verify? _Fundamentals_ _Obligra Verify gives organizations a retained record layer for AI-assisted workflows, so important decisions can be found, reviewed, and checked later by business context instead of reconstructed from scattered systems._ ## The problem AI is increasingly used to support real decisions in production systems. In healthcare, financial services, insurance, legal operations, customer support, and other high-accountability environments, these decisions may be reviewed later by clinicians, auditors, regulators, legal reviewers, risk leaders, or operations teams. When that happens, the question is not only whether the system was available or responsive. The question is usually more specific: - What input was used? - What response was produced? - What context influenced the result? - What decision was made at that point in time? Traditional logging systems were not designed to answer these questions. Logs can help engineers understand system behavior. They can show whether a service ran, whether an API call completed, or whether an error occurred. But they usually do not create a retained decision record that business, legal, compliance, audit, risk, or operational reviewers can search and inspect later by business context. That is the gap Obligra Verify is built to close. Verify ensures that when an AI-assisted decision is revisited, the original retained record is available as the record created for that workflow event. ## What organizations usually do today Without a retained record layer, organizations usually try to reconstruct the event from whatever artifacts are available. They may search application logs, model provider dashboards, prompt histories, screenshots, support tickets, case notes, database rows, internal chat threads, or source-system records. Each source may be useful, but each one tells only part of the story. Application logs may show that a service ran at a certain time. A provider dashboard may show that a model request occurred. A support ticket may describe what someone thought happened. A screenshot may show one output at one point in time. A source system may hold the business record, but not the AI-assisted context around the workflow. None of these are designed to be the retained decision record for the AI-assisted workflow. That matters because the person reviewing the event is often not trying to debug a service. They are trying to answer a business question: what happened in this claim, this encounter, this transaction, this case, this workflow, or this customer-impacting event? ## Why this breaks down The current approach is inefficient because it depends on reconstruction. Reconstruction is slow, inconsistent, and fragile. It often requires engineering help. It may depend on logs that were rotated, screenshots that were copied manually, tickets that were written after the fact, or model-provider artifacts that do not include the business identifiers reviewers actually use. It can also produce different answers depending on which system someone searches first. This problem becomes harder as GenAI adoption spreads across the enterprise. One department may use one model provider. Another may use a different provider. A workflow may start with a hosted model API and later move to a private endpoint. A SaaS product may include embedded AI features with limited metadata. A model version may change before an audit or legal review occurs. The AI output happened once. The review happens later. If the organization did not retain the right record at the time of the workflow, the later review depends on detective work. Obligra Verify is designed to reduce that dependency. ## What Verify is Obligra Verify is a managed system of record for AI-assisted decisions. When an application or workflow uses AI, it can submit selected decision context to Verify. Verify creates a retained decision record that can later be searched, inspected, and checked from the Verify Console. In simpler terms, Verify keeps a reviewable record of the AI-assisted workflow event. The customer’s application still runs the workflow. The customer’s model provider still generates the output. The customer’s source systems still hold their business data. Verify gives the organization a retained record layer around the AI-assisted step, so the event can be reviewed later without relying on memory, screenshots, or scattered technical artifacts. ## The record Verify creates A retained decision record is the saved record Verify creates from the context the customer chooses to submit. That record is meant for later review. It connects the AI-assisted workflow event to the business context around it. A retained record may include the workflow ID, the environment, operational identifiers such as claim ID or encounter ID, model provider, model ID, prompt reference, response or response reference, validation state, review status, retention date, verification state, and supporting metadata. Those fields matter because they make the record useful to more than one audience. A developer may care that the workflow submitted the record correctly. A compliance officer may care that the record can be found months later. A legal reviewer may care that the record is tied to a case or dispute. A risk officer may care that the same record pattern works across different models and workflows. An architect may care that the retained record layer remains stable as the GenAI stack changes. Verify is built around that shared review need. ## How Verify works The basic pattern is simple. A customer workflow uses AI or produces an AI-assisted response. The workflow sends selected decision context to the Verify API. Verify creates a retained decision record and returns a capture receipt with the record ID and record link. Later, an authorized user opens the Verify Console, searches by business context, inspects the record, and checks the verification state. The important point is that review starts from the business context, not from the original prompt. A reviewer may know the claim ID, encounter ID, transaction ID, case ID, policy ID, or workflow ID. They may not know the prompt text, provider request ID, timestamp, or internal trace ID. Verify is designed to support that reality. ### Direct and governed deployments Direct deployments connect the workflow straight to the Verify API. They are commonly used for builder, sandbox, evaluation, and internal testing — situations where fast feedback matters more than separating governance from application code. Governed deployments place a Customer-Owned Capture Boundary between the workflow and the Verify API. They are commonly used for production, enterprise, and regulated workloads — situations where capture decisions and field retention need to be enforced inside the customer environment before any information reaches Verify. ### The customer-owned capture boundary Many organizations begin with direct integrations during evaluation and onboarding. Production deployments often introduce a Customer-Owned Capture Boundary inside their own environment before information is transmitted to Verify. The boundary lets the organization decide which interactions become retained decision records, which fields may leave the environment, and how governance policies are applied before transmission. For deeper architecture detail, see [Deployment Topology](/resources/deployment-topology) and [Customer Integration Patterns](/resources/customer-integration-patterns) . ### Capture policies Many organizations use capture policies to determine which workflow events should become retained decision records and which fields are approved for transmission to Verify. Two governance controls are common: a **Capture Decision Policy** that decides whether a given interaction should be captured or skipped, and a **Field Retention Policy** that decides which fields may be transmitted to Verify and which should be redacted, truncated, or held back entirely. For detailed implementation guidance, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ![The Verify lifecycle from AI-assisted moment to review-ready evidence. Six horizontal stage cards: 01 AI-Assisted Workflow Event (an AI-assisted step occurs inside the customer workflow), 02 Capture (selected decision context becomes a retained decision record; teal-bordered hero card with a dark teal CAPTURE header band marking the customer-owned boundary moment), 03 Retain (the record is held by Verify with stable operational context), 04 Retrieve (authorized reviewers find the record by claim, transaction, or workflow context), 05 Verify (record integrity is confirmed at review time), and 06 Evidence (reviewers produce evidence for audit, compliance, and review surfaces; dark teal hero terminal card with an EVIDENCE header band). Stages 1 and 2 sit under a warm beige Customer-Operated ownership band; stages 3 through 6 sit under a light teal Obligra-Operated ownership band. An HTTPS arrow marks the boundary crossing between stages 2 and 3. Footer caption: The Verify lifecycle: from an AI-assisted moment to review-ready evidence.](/diagrams/obligra-verify-lifecycle.svg) * The Verify lifecycle in six stages. Customer workflows originate the AI-assisted event and own the capture moment; Verify retains, retrieves, verifies, and produces review-ready evidence. * ## Before Verify and with Verify Before Verify, a review often begins with scattered evidence. A compliance, legal, risk, or operations reviewer may need to ask engineering to pull logs, check model dashboards, search tickets, compare timestamps, and trace application behavior. The process can take time, and the result may still be incomplete. With Verify, the workflow creates a retained decision record when the AI-assisted event occurs. Later, the reviewer has a record that is tied to workflow identity, operational context, model metadata, review status, and verification state. This does not remove the need for business review. It gives that review a better starting point. ## Why logging is not enough Logs are valuable. They help engineering and operations teams understand system behavior. They can show that a service ran, an API call completed, an error occurred, or a request moved through a system. That is not the same as a retained decision record. A log is usually written for debugging. A retained decision record is written for review. A log may be searched by timestamp, request ID, or trace ID. A retained decision record should be searchable by business context, such as claim ID, encounter ID, transaction ID, case ID, generated summary ID, or workflow ID. Logs also vary by system. Model provider logs, application logs, cloud logs, and SaaS logs each have their own format and retention behavior. They may not include the business identifiers, review status, or verification state that compliance, legal, audit, and risk reviewers need. Verify is not trying to replace logs. It solves a different problem. It gives organizations a retained record layer for AI-assisted workflow events. ## Why this matters now GenAI changes the evidence problem. Traditional software workflows often followed predictable application logic. GenAI workflows add model responses, provider metadata, prompts, retrieved context, review status, and model-version changes into the business process. The response may not be reproducible later. The model provider may change. The prompt may change. The application may change. The reviewer still needs to know what happened. This is why a retained record layer matters. The organization needs a way to preserve the record of the AI-assisted workflow event in a form that compliance, legal, risk, audit, operations, and technical leaders can use later. That record should not depend entirely on one model provider’s dashboard, one team’s logging style, or one engineer’s ability to reconstruct the event. Verify gives organizations that layer. ## Industries Verify serves The same pattern appears across regulated and high-accountability workflows: an AI-assisted output is created now, but the review happens later. ## Who uses Verify Different roles care about Verify for different reasons. A compliance leader wants to know whether records tied to regulated workflows can be found and reviewed later. A legal reviewer wants records tied to claims, disputes, investigations, or cases. A risk officer wants consistency across high-impact workflows, especially when different models or departments are involved. An audit leader wants records that can be traced to the business event under review. Architects and platform leaders care about the system design. They need a record layer that can work across model providers, cloud services, private endpoints, and changing application patterns. Developers care about the integration path. They need a clear API or SDK pattern that lets their workflow submit selected decision context without building a custom evidence system from scratch. Verify is built for that shared operating model: business reviewers need usable records, and technical teams need a controlled way to create them. ## Key use cases The use cases differ by industry, but the pattern is consistent. AI-assisted output is created during the workflow, while review often happens later. Verify gives the organization a retained record that connects the output to workflow identity, operational context, model metadata, review state, and verification state. | Use case | Customer problem | How Verify helps | | --- | --- | --- | | AI-assisted summary review | A generated summary may need review weeks or months later. | Verify keeps a retained record tied to workflow, model, and business context. | | Claim or case review | Reviewers need records tied to claim ID, policy ID, case ID, or routing decision. | Verify supports retrieval by operational context. | | Transaction dispute review | Risk and legal reviewers need consistent records across models and workflows. | Verify preserves retained records independent of provider-specific artifacts. | | Model migration review | A model provider or model version changes over time. | Verify keeps the retained record layer consistent while the model layer changes. | | Audit preparation | Audit teams need records that can be found and inspected later. | Verify gives reviewers a searchable retained record tied to the workflow event. | | Incident investigation | Operations teams need to understand what was retained during an AI-assisted event. | Verify provides a reviewable record and verification state. | ## What Verify is built to do Verify is built to create and manage retained decision records for AI-assisted workflows. It gives organizations a place to retain the record of an AI-assisted event, retrieve that record by business context, inspect the associated workflow and model context, and check the record’s verification state. The product is strongest where later review matters. That includes audit preparation, compliance review, legal review, risk review, operational investigation, customer dispute review, model migration review, and internal control review. This is the reason Verify exists: AI responses are produced now, but review often happens later. In production deployments, many organizations establish a Customer-Owned Capture Boundary before information is transmitted to Verify, so governance decisions can be applied inside their own environment. ## How Verify works with your existing systems Verify is designed to work alongside the systems customers already use. The customer application continues to run the workflow. The model provider continues to produce the AI-assisted output. The source system continues to own the business data. The customer’s review process continues to decide what is acceptable, approved, escalated, or rejected. Verify adds the retained record layer around the AI-assisted step. This makes adoption practical. Customers do not need to replace their EHR, claims platform, transaction system, case system, model provider, or review workflow to begin using Verify. They need to decide which workflow should submit selected decision context and which identifiers should be used for later retrieval. ## Customer responsibilities and Verify responsibilities The customer is responsible for the workflow itself and for the business decisions made around it. That responsibility covers workflow ownership (which workflows use AI), model selection (which model provider is used), source-system ownership (which systems remain authoritative), operational identifier selection (which identifiers are retained so records stay findable later), capture policy decisions (which interactions become retained decision records), field retention policy decisions (which fields are approved for transmission to Verify), review process ownership (how records are reviewed once retained), and business approval and escalation decisions (when a decision is approved, escalated, or rejected). Verify is responsible for the managed decision record platform. That responsibility covers the Verify API for receiving approved decision context, the creation and retention of retained decision records, retrieval services that surface records by operational context, verification services that confirm record integrity, evidence generation for compliance and review surfaces, the Verify Console used by authorized reviewers, and the day-to-day managed platform operations behind all of these. This separation is important because it keeps the customer in control of their business process and their capture boundary, while giving reviewers a consistent place to find the retained record. ## Why model-agnostic matters Most organizations will not use one AI model forever. Different departments may choose different model providers. A workflow may move from one provider to another. A cloud team may use a managed model service. A sensitive workload may move to a private endpoint. A SaaS tool may introduce its own embedded AI feature. That flexibility is useful, but it fragments evidence. Each provider may expose different metadata, logs, request IDs, retention options, and administrative views. If review depends entirely on provider-specific artifacts, the review process becomes harder every time the model stack changes. Verify gives organizations a consistent retained record layer across those changes. The model can change. The record layer remains understandable. ## Where verification fits Verification helps reviewers understand the current integrity state of a retained decision record. It answers a narrow but important question: does this retained decision record still align with the integrity evidence associated with it? Verification does not decide whether the AI response was correct, whether the business decision was approved, whether a clinical summary was appropriate, whether a legal conclusion is valid, or whether a model was fair or accurate. Those determinations remain part of the customer’s review process. Verify gives the reviewer a record and a verification state. The customer applies judgment, policy, and review. ## What to read next If this page makes the problem clear, the next step is Introduction to Obligra Verify. That guide explains the product in more detail, including how records are created, how retrieval works, and how Verify fits into the broader Resource Hub. [Continue Introduction to Obligra Verify A deeper walkthrough: how records are created, how retrieval works, and how Verify fits into the broader Resource Hub. →](/resources/introduction-to-verify) Related docs [Why AI Decisions Need a System of Record](/resources/why-ai-decisions-need-system-of-record) [A Model-Agnostic Record Layer](/resources/model-agnostic-record-layer) [Retrieval by Operational Context](/resources/retrieval-by-operational-context) [Record Integrity and Verification](/resources/record-integrity-and-verification) [Quickstart](/resources/quickstart) [Using AI Assistants with Verify](/resources/using-ai-assistants-with-verify) --- --- title: What Auditors Look For in AI-Assisted Workflows slug: audit-readiness-ai-workflows category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/audit-readiness-ai-workflows canonicalUrl: "https://obligra.ai/resources/audit-readiness-ai-workflows" llmTags: - llm-aligned - canonical-concept - audit-readiness - review-ready-evidence - retrieval-model - evidence-vs-logs - ai-assisted-operational-workflows - retained-decision-records - canonical-concept-source - retrieval-tier-2 --- # What Auditors Look For in AI-Assisted Workflows _Fundamentals_ _An auditor arriving to review an AI-assisted decision is not asking new compliance questions. They are asking the same five questions they have always asked — what happened, who approved it, what controls applied, was it changed, can it be trusted. The difference is that the artifacts AI-assisted workflows produce by default do not answer those questions. Logs describe activity. Tickets capture annotations. Screenshots capture UI state. None of them is the retained record of the AI-assisted decision. This page walks the auditor’s starting point, what changes when a decision record is preserved at execution time, and how the five recurring auditor questions map to fields that already live inside the record._ ## 01. Overview An auditor arriving to review an AI-assisted decision is not asking new compliance questions. They are asking the same five questions reviewers have always asked: what happened, who approved it, what controls applied, was it changed, and can it be trusted. What changes with AI-assisted workflows is the artifact those questions land on. A traditional deterministic workflow leaves behind the inputs it received and the rules it ran. An AI-assisted workflow leaves behind logs, tickets, screenshots, and downstream system state — but rarely the artifact an auditor would actually want to inspect: the retained record of the AI-assisted moment itself. > Review moments happen later. The record must already exist. ![What Auditors Need. A vertical flow showing how an AI-assisted decision becomes an auditor review. Stage 01 An AI-Assisted Decision is produced inside the customer workflow. Stage 02 A Question Is Raised about that decision, weeks or months later, by an auditor, regulator, compliance officer, or internal reviewer. Stage 03 Auditor Review begins, and at this point the auditor needs five things to evaluate the decision: Context, the operational situation the workflow was in; Controls, which customer-side policies applied; Review History, what humans did with the AI-assisted output; Verification, whether the retained record still matches what was captured; Evidence, the artifact under review itself. Stage 04 Decision Record, the retained artifact that carries all five answers at once. Bottom callout: A retained decision record is the artifact that lets auditor review begin from evidence, not from investigation.](/diagrams/obligra-verify-what-auditors-need.svg) * The auditor’s starting point. Five needs upstream of the review, one retained artifact that carries all five answers at once. * The rest of this page walks the auditor’s problem in turn — what the auditor needs, what review looks like without a retained record, what review looks like with one, how the five recurring questions map onto the record itself, where this matters across industries, and how Verify supports audit programs without replacing them. ## 02. What auditors actually need Audit and review programs converge on the same operational requirements across industries. The categories below show up regularly during real audit work, regardless of the underlying regulation or industry vocabulary. | Audit focus | Why it matters | Workflow evidence the auditor expects | | --- | --- | --- | | Model input | The input the workflow actually saw is the starting point of any review. | The exact input fields submitted to the model, including the operational context (claimId, encounterId, transactionId) the workflow used. | | Generated output | The AI-assisted output as produced is the artifact under review. Reconstructions and paraphrases are not equivalent. | The original AI-assisted output retained at capture time, available later through retrieval by operational context. | | Workflow context | Reviewers need to know which workflow produced the output, in which environment, against which operational scope. | workflowId, environment (Sandbox or Production), and the non-sensitive model metadata the customer chose to retain. | | Review and approval state | Whether the AI-assisted output was reviewed, approved, escalated, or overridden is part of the decision record. | Review status, reviewer references (per the customer’s access program), and timestamps for each review step. | | Identifiers and timestamps | Reviewers retrieve by the business identifiers their teams already use; timestamps anchor the record to the moment the workflow ran. | Stable customer-side identifiers (claimId, encounterId, transactionId) and capture timestamps in a consistent time reference. | | Lifecycle state | The record’s state (recorded, validated, attested, verified, superseded) tells the reviewer how much trust to place in the content. | Current lifecycle state of the retained record, with its history of state transitions tied to the same operational context. | | Verification | Reviewers expect to confirm that the retained record still matches what was captured at execution time. | Integrity reference and verification result, evaluated at review time, on the same record under review. | The table is a reference, not a checklist. The audit posture it points at is operational: each row exists because reviewers consistently ask for that field when an AI-assisted decision is questioned later. The retained decision record is designed around the same shape. ## 03. Audit review without Verify When no retained decision record exists, audit review becomes an evidence-gathering exercise. The auditor arrives with a question, the customer team gathers whatever artifacts remain, and the response is assembled by hand. The cost is paid every time review happens. ![Audit Review Without Verify. A vertical flow showing the painful audit-review path when no retained decision record exists. Stage 01 the auditor arrives with a review question. Stage 02 Fragmented Sources: the auditor must gather evidence from five scattered artifacts in parallel, Logs that describe system activity, Tickets that capture human annotations after the fact, Screenshots that capture UI state but not the underlying decision, Dashboards that summarize aggregate behavior, and Emails that preserve narrative correspondence. None of these were designed to be the retained record of an AI-assisted decision. Stage 03 Manual Investigation: the auditor assembles those five artifacts by hand into something that approximates the original decision, paying the assembly cost on every audit. Stage 04 Audit Response: the response is based on a reconstructed approximation rather than a retained record. Callout: Audit becomes evidence gathering.](/diagrams/obligra-verify-audit-review-without-verify.svg) * Without a retained record, audit becomes evidence gathering. Each artifact is useful for the purpose it was designed for, and not for the purpose under review. * The artifacts that survive on this path were each built for a different purpose. Logs describe system activity, not decision content. Tickets capture human-side annotations after the fact. Screenshots capture UI state but not the underlying decision. Dashboards summarize aggregate behavior. Emails preserve narrative correspondence. None of them is the retained record of what the AI-assisted workflow produced. The compounding consequence is that reconstruction works for a handful of decisions reviewed individually and does not scale to audit sampling, dispute volume, regulator inquiries, or incident response. AI-assisted workflows make reconstruction structurally weaker: the prompt template may have moved on, the model may have been swapped, the retrieved context may return different results, and the workflow may only retain its final state. Even when reconstruction produces a similar output, similar is not the same as the original. ## 04. Audit review with Verify When a decision record is preserved at execution time, audit review changes shape. The auditor arrives with the business identifier the customer team already uses, the identifier resolves to the retained record, and review history, verification result, and the evidence itself are all inspected on the same artifact. ![Audit Review With Verify. A horizontal flow showing the audit-review path when a retained decision record exists. Stage 01 Business Context: the auditor arrives with the case, claim, transaction, encounter, or workflow identifier their team already uses. Stage 02 Decision Record: the business identifier resolves to the preserved decision record captured at execution time. Stage 03 the auditor inspects three things at once on the same retained artifact: Review History showing what humans did with the AI-assisted output, Verification confirming the retained record still matches what was captured, and Evidence showing the input, context, and output that produced the decision. Stage 04 Audit Response: the response is based on the retained record, not on reconstruction. Callout: Audit begins with evidence.](/diagrams/obligra-verify-audit-review-with-verify.svg) * With a retained record, audit review begins with the business identifier the auditor already has. Review history, verification, and evidence are all available on one artifact. * The shape of the work changes. The auditor does not re-run the system, does not approximate prior state, and does not stitch logs together to construct a narrative. They retrieve the record by an identifier their team already uses to talk about the case, the claim, the encounter, the transaction, or the workflow, and the retained artifact answers the review questions directly. The retained record carries the input the workflow saw, the AI-assisted output as generated, the workflow context (workflowId, environment, model metadata where applicable), review and approval state, escalation history, identifiers and timestamps, lifecycle state, and a verification result. The auditor inspects all of this on a single artifact, which is the point. ## 05. Auditor questions and record evidence The five questions auditors ask map onto five fields that already live inside the retained record. The mapping is worth being explicit about, because it is the reason the record shape exists. ![Auditor Questions and Record Evidence. A mapping visual that shows how the five questions auditors actually ask are answered by five fields inside a retained decision record. Left column, Auditor Questions: What happened, Who approved it, What controls applied, Was it changed, Can it be trusted. Right column, Record Evidence: Workflow Context, Review History, Validation State, Lifecycle State, Verification State. Horizontal arrows connect each question to the corresponding record field. Bottom callout: Every question the auditor asks resolves to a field that already exists inside the retained decision record, no investigation required to find it.](/diagrams/obligra-verify-auditor-questions-and-record-evidence.svg) * The auditor’s five recurring questions resolve to five fields that already exist inside the retained decision record. Investigation is not the starting point. * **What happened** resolves to *Workflow Context*. The workflowId, the environment, the operational identifiers, and the non-sensitive model metadata establish which decision is under review and which workflow produced it. **Who approved it** resolves to *Review History*. Reviewer references, overrides, escalations, releases, and review timestamps establish what humans did with the AI-assisted output once it was produced. **What controls applied** resolves to *Validation State*. Policy outcomes, required-check results, and release-control status establish which customer-side policies the record passed through before it moved further in the workflow. **Was it changed** resolves to *Lifecycle State*. The current state (recorded, validated, attested, verified, superseded, revoked, blocked, replaced) and the history of state transitions establish what has happened to the record since it was captured. **Can it be trusted** resolves to *Verification State*. The integrity reference and the verification result confirm that the retained record still matches what was captured at the AI-assisted moment. This is the question that opens almost every after-the-fact review, and it is the field most worth resolving before review begins. ## 06. Where this matters in production The audit-review shape repeats across industries. Reviewers arrive with the business identifier their team already uses, the review program asks the same five recurring questions, and the retained decision record answers them. The vocabulary changes; the operational pattern does not. ### Healthcare and telehealth AI assistance appears in clinical documentation, encounter summarization, triage, care navigation, and coding support. Reviewers arrive with an encounterId, an episodeOfCareId, a patient reference from the authoritative system, or a reviewCaseId. They expect the AI-assisted output as it existed at the time the workflow ran, the encounter context the workflow saw, the clinician review state, and the verification result for the retained record — preserved alongside the final signed note in the clinical system. ### Financial services AI assistance appears in fraud review, transaction classification, customer operations, audit workflows, and financial-crime analysis. Reviewers arrive with a transactionId, a disputeId, an escalationId, an account reference, or a reviewCaseId. They expect the AI-assisted output that influenced the operational decision, the transaction context, the escalation history, the review state, and the verification result tied to the same operational context. The transaction stays in the financial system; the AI-assisted record is what the review program needs preserved alongside it. ### Insurance AI assistance appears in claims review, underwriting support, fraud analysis, and operational routing. Reviewers arrive with a claimId, a policyId, an appealId, or a reviewCaseId. They expect the AI-assisted output that supported the original claims decision, the claim context at the time of the decision, the routing or escalation state, and any human review activity tied to the same operational context. Claims sit quietly for months before an appeal, a regulator inquiry, an internal sampling audit, or an SIU investigation reopens the question — which is why the record must already exist when the review begins. The shared pattern is straightforward. Customer teams already have logs, tickets, screenshots, dashboards, and downstream systems. What they are missing is the retained decision record that answers the five auditor questions on a single artifact, retrieved by the business identifier reviewers already use. ## 07. What Verify supports, and what it does not Verify is intentionally scoped. Its role inside an audit program is narrow and worth stating plainly so audit and review teams can evaluate it accurately during due diligence. ### What Verify supports - A retained decision record layer for AI-assisted decisions, preserved at the moment the workflow runs and anchored to the customer-attached operational context. - A retrieval surface that resolves business identifiers (claim, encounter, transaction, case, workflow) to the retained record without requiring reviewers to know prompts, model versions, or trace IDs. - A verification result on the retained record, evaluated at review time, that confirms the record still matches what was captured. - A stable record shape across cloud, hybrid, and on-prem deployments, so a single audit program can span a portfolio of AI-assisted workflows without per-workflow custom evidence handling. ### What Verify does not replace - The customer’s compliance or audit program. Policies, controls, regulatory interpretation, model risk management, and review outcomes remain customer-owned. - Authoritative systems of record for operational state. EHR, claims platforms, accounting platforms, CRM, and policy admin remain the source of truth for the underlying business state. - Observability, monitoring, or telemetry. Runtime activity remains the domain of the customer’s existing observability stack. - Human judgment. Verify confirms that the retained record matches what was captured; it does not assert that the original AI-assisted output was the correct outcome. > Verify supports the audit, review, and accountability programs the customer team already runs. It does not replace them. The customer team’s governance program continues to determine policies, controls, regulatory interpretation, and review outcomes. ## 08. Reference summary AI-assisted workflows produce decisions that may be reviewed weeks or months later by audit, compliance, legal, risk, fraud, clinical, or operations teams. The questions reviewers ask have not changed; the artifacts AI-assisted workflows produce by default do not answer them. Audit review without a retained record turns into evidence gathering from logs, tickets, screenshots, dashboards, and emails — each useful for its original purpose, none of them the retained record of the AI-assisted moment. Reconstruction may produce a similar output, but similar is not the same as the original. The cost is paid on every review. Audit review with a retained record begins with the business identifier the auditor already has. The record carries workflow context, review history, validation state, lifecycle state, and verification state on a single artifact — the same five fields the five recurring auditor questions resolve to. Investigation is not the starting point. Obligra Verify provides the retained decision record layer that turns audit review into retrieval. The customer team continues to own the audit program; Verify supplies the structured evidence that program operates on. ### Related documentation - [Why retrieval beats reconstruction — the foundational thesis behind the retained decision record layer.](/resources/why-retrieval-beats-reconstruction) - [Evidence vs logs — why retained decision records are a different surface from application logs.](/resources/evidence-vs-logs) - [Working with Decision Records in Verify — the customer-side operations for retrieving, inspecting, and verifying retained records.](/resources/working-with-decision-records) - [Verification Lifecycle — the five-stage trust progression auditors use when judging whether a retained record can be relied on.](/resources/verification-lifecycle) - [Retrieval by Operational Context — how auditors find a specific retained record from the business identifier they already have.](/resources/retrieval-by-operational-context) - [Structure of a Decision Record — the field-by-field reference for the retained record.](/resources/structure-of-a-decision-record) - [Operational Context Mapping — how customer teams choose the business identifiers reviewers later retrieve by.](/resources/operational-context-mapping) - [Compliance Approach — how Verify supports broader compliance and governance programs.](/resources/compliance-approach) --- --- title: Capture Boundary vs Proxy slug: capture-boundary-vs-proxy category: Architecture retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/capture-boundary-vs-proxy canonicalUrl: "https://obligra.ai/resources/capture-boundary-vs-proxy" llmTags: - llm-aligned - architecture-core - definitional-anchor - canonical-concept-source - retrieval-tier-2 --- # Capture Boundary vs Proxy _Architecture_ _Two terms appear together in Verify deployments and are commonly conflated: the Customer-Owned Capture Boundary and the Customer-Owned Proxy. They are related, but they are not the same. The boundary is the architectural concept — the customer-side place where the customer decides what becomes a decision record and which fields may leave the customer environment. The proxy is the implementation pattern most teams use to realize that concept in code. This is the authoritative definitional anchor for both terms across the Resource Hub._ ## 01. Overview Two terms appear together across this documentation set and are commonly conflated: the Customer-Owned Capture Boundary and the Customer-Owned Proxy. They are related, but they are not the same artifact. > The Customer-Owned Capture Boundary is the architectural concept. The Customer-Owned Proxy is the implementation pattern most teams use to realize that concept. ![Capture Boundary vs Proxy: how they relate. A two-layer diagram showing the architectural concept on top and the implementation pattern below. Top layer, the architectural concept: the Customer-Owned Capture Boundary, a single rectangle representing the customer-side governance boundary where the customer evaluates Capture Decision Policy and Field Retention Policy before any data leaves the customer environment. Bottom layer, the implementation pattern: the Customer-Owned Proxy, a deployable service the customer runs that implements that boundary, with three labeled internal components, Capture Decision Policy evaluator, Field Retention Policy evaluator, and the approved-fields forwarder that physically transmits the approved record payload to the Verify API. A vertical mapping arrow connects the two layers with the labels ARCHITECTURAL CONCEPT on top and IMPLEMENTATION PATTERN below. Footer callout: The Customer-Owned Capture Boundary is the concept. The Customer-Owned Proxy is the most common implementation of that concept.](/diagrams/obligra-verify-capture-boundary-vs-proxy.svg) * Two layers of the same idea. The boundary is the concept every customer must reason about; the proxy is the concrete service most customers deploy to realize it. * ## 02. Customer-Owned Capture Boundary The Customer-Owned Capture Boundary is the customer-side boundary where the customer decides what becomes a decision record and which fields may leave the customer environment. It is an architectural concept, not a product: the place where governance runs before any data is transmitted to Verify. The boundary carries two responsibilities. The Capture Decision Policy decides whether an interaction becomes a decision record. The Field Retention Policy decides which fields may leave the customer environment. Both decisions are evaluated inside customer infrastructure, by code the customer owns and operates, before the approved record payload crosses the boundary. The boundary exists because governance happens where the data lives. A reviewer who later asks “what was preserved and why?” should not have to inspect a remote service to answer that question. The boundary keeps that answer inside the customer environment, where the customer’s security, audit, and platform teams already have visibility into their own policy evaluations. ## 03. Customer-Owned Proxy The Customer-Owned Proxy is the deployable service the customer runs to implement the boundary. It is delivered as a CloudFormation template, a Terraform module, or as customer-provisioned infrastructure, and it lives inside the customer environment alongside the application that produces the AI-assisted decision. Inside the proxy, three things happen in sequence. The Capture Decision Policy is evaluated against the interaction to decide whether it becomes a decision record. The Field Retention Policy is evaluated against the captured fields to decide which ones may leave the customer environment. The approved-fields forwarder then transmits the approved record payload to the Verify API over standard HTTPS. The proxy is the most common way customers realize the boundary in production, but it is not the only conceivable implementation. The relationship is one of concept to pattern, not concept to product. A customer team could reasonably choose a different implementation shape; the architectural commitments of the boundary remain the same. ## 04. How to read these terms across the Resource Hub The two terms surface together throughout the Resource Hub. Holding them distinct keeps the reading order clear. When the documentation talks about *where governance runs*, who owns the governance posture, or what crosses the customer environment, it is talking about the Customer-Owned Capture Boundary. That is the concept layer. The boundary’s responsibilities — the Capture Decision Policy, the Field Retention Policy, the approval gate before transmission — are architectural commitments that apply regardless of which deployment artifact realizes them. When the documentation talks about *what gets deployed*, which service evaluates the policies, or how the forwarding service is provisioned, it is talking about the Customer-Owned Proxy. That is the implementation layer. The proxy’s shape — CloudFormation, Terraform, customer infrastructure — is a deployment choice that realizes the boundary’s architectural commitments in code. The two terms are related, but they are not interchangeable. Using them precisely keeps the Resource Hub navigable for both architects (who reason in concepts) and operators (who reason in deployed artifacts). ## 05. Where to go next For the deployment context that surrounds both terms, see [Deployment Topology](/resources/deployment-topology) . That page anchors the boundary inside the broader customer deployment shape and walks the direct vs governed deployment patterns in full detail. For the capture pattern that lives behind the boundary, see [Server-Side Capture Pattern](/resources/server-side-capture-pattern) . That page covers how the customer backend or proxy calls the Verify API in both the direct and governed shapes. For the two policies the boundary evaluates, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . That page is the operational reference for both the Capture Decision Policy and the Field Retention Policy. --- --- title: Customer Integration Patterns slug: customer-integration-patterns category: Architecture retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/customer-integration-patterns canonicalUrl: "https://obligra.ai/resources/customer-integration-patterns" llmTags: - llm-aligned - architecture-core - integration - canonical-concept-source - retrieval-tier-2 --- # Customer Integration Patterns _Architecture_ _Every Verify integration combines two independent architectural decisions: a runtime pattern (where capture executes) and a governance pattern (how capture decisions and field retention are enforced). The four supported runtime patterns are backend service, AWS Lambda, container or ECS, and queue-based capture. The two supported governance patterns are direct integration and the Customer-Owned Proxy. Direct integration fits builder, evaluation, and Sandbox workflows. Governed integration fits Production, enterprise, and regulated workloads, where capture and field-retention decisions are reviewed, versioned, and enforced inside the customer environment before any record reaches Verify._ ## Overview Customer teams approaching their first Verify integration generally arrive with the same question: where, structurally, should this fit inside the systems we already run? The deliberate answer is that it should fit anywhere capture already needs to happen. Verify integrations live entirely inside the customer's trusted server-side environment. There is no proprietary deployment shape required, no Verify-managed agent, and no obligation to adopt a specific runtime — customer teams pick the integration pattern that matches the runtime they already operate. In practice, five integration shapes cover the vast majority of customer architectures observed in production. Four of them are capture-runtime patterns — capture can run from a backend service, from an AWS Lambda function, from a long-running container or ECS service, or asynchronously behind a customer-owned queue. The fifth is a downstream notification pattern: customer-owned webhook receivers consume Verify events to drive review queues, case updates, and audit-preparation surfaces. These shapes are not mutually exclusive, and the strongest production integrations rarely use only one. A common shape composes two of them — queue-based capture on the write path plus webhook receivers on the read path — running inside the customer's existing container or Lambda runtime. The pattern names below are a vocabulary for reasoning about the integration, not a menu of mutually exclusive options. > Webhook notification is a downstream surface, not a capture runtime. > > > > > Capture runs inside one of the four capture runtimes. Webhook receivers consume Verify activity to drive customer-side surfaces. The two decisions are independent and most production integrations include both. ## Where should I start? The right starting point depends on what the customer team is doing right now. The table below maps the most common situations to the page that picks up where this one leaves off. | Situation | Recommended starting point | | --- | --- | | Just evaluating Verify | | | Building a first integration | | | Choosing an architecture | You are on the right page — keep reading. | | Deploying into AWS | | | Something is not working | | ## Why this matters The integration-pattern decision is not cosmetic. It shapes where credentials live, how retries behave, how operational context propagates, how Sandbox and Production stay separated, and which customer-side surfaces consume Verify activity. In practice, the cost of getting this decision wrong shows up weeks or months later, in patterns that are recognizable but expensive to unwind: a service that holds a Verify credential it should not need, a Lambda function whose timeout window quietly swallows capture retries, a backend service whose queue is also doing capture but without the queue’s retry posture. The cleanest way to think about the tradeoffs is along three axes. Credentials follow the runtime: the chosen pattern determines whether the Verify API key is read from a Lambda secret, a container env, a backend service config, or injected per-message into a worker — which in turn determines what the customer’s existing secret-management program needs to know about Verify. Retry behavior also follows the runtime, and the tradeoff is sharper than it looks at first. Synchronous request-path capture has to respect upstream timeouts; queue-based capture can use longer bounded retries; Lambda capture has to respect function timeouts. Each pattern has its own operational discipline, and getting the discipline wrong is where the duplicate-record and lost-record patterns customer teams encounter most often come from. Finally, operational-context propagation, environment separation, and downstream surface composition all follow the same logic. Where workflowId and operationalContext are assembled depends on which runtime owns the AI-assisted step; Sandbox-versus-Production discipline lives inside the customer’s existing deployment system; and whether the integration includes webhook receivers depends on whether customer-side review queues, case updates, or audit workflows need to react to Verify activity. Each of those choices becomes easier when the runtime pattern is named explicitly up front. ## Runtime patterns vs governance patterns A Verify integration is the composition of two architectural decisions, and the most common confusion during a first architectural review comes from treating them as if they were one. The first decision is structural: *where* does capture execute? That is the runtime pattern. The second is procedural: *how* are capture decisions and field retention enforced? That is the governance pattern. The two decisions are independent, and every customer chooses both. ![Runtime times Governance decision framework for Verify integrations. A 4 by 2 matrix combines four runtime patterns rows (Backend Service, AWS Lambda, Container or ECS, Queue Worker) with two governance patterns columns (Direct integration suited to builder evaluation and sandbox; Governed integration suited to production enterprise and regulated workloads). Each of the eight cells shows the architecture chain and the best-fit workload shape. Backend Service plus Direct: Customer Backend to Verify API for synchronous request paths in builder and sandbox. Backend Service plus Governed: Customer Backend to Customer-Owned Proxy to Verify API for production synchronous request paths under governance. Lambda plus Direct: Lambda to Verify API for event-driven workflows in builder and sandbox. Lambda plus Governed: Lambda to Customer-Owned Proxy to Verify API for production event-driven workflows under governance. Container plus Direct: Container to Verify API for long-running services in builder and sandbox. Container plus Governed: Container to Customer-Owned Proxy to Verify API for production long-running services under governance. Queue Worker plus Direct: Worker to Verify API for asynchronous high-volume workflows in builder and sandbox. Queue Worker plus Governed: Worker to Customer-Owned Proxy to Verify API for production asynchronous high-volume workloads under governance. The Verify API is the only external boundary. Customer teams choose both decisions independently.](/diagrams/obligra-verify-runtime-governance-decision-framework.svg) * Pick the runtime that already hosts the customer’s AI-assisted workflow. Pick the governance pattern that matches the workload’s audit and review obligations. The Verify API is the same endpoint in every cell. * In practice, the four runtime patterns — backend service, AWS Lambda, container or ECS, queue worker — cover the runtimes where customer AI-assisted workflows actually run. The two governance patterns — direct integration and Customer-Owned Proxy — cover whether capture decisions and field retention are evaluated inside the customer environment before any record reaches Verify. Choosing both axes deliberately is the single highest-leverage architectural decision in a Verify integration; choosing only one is the most common source of late-stage rework. > Both decisions are required. Runtime pattern alone does not describe whether capture decisions and field retention are enforced inside the customer account. Governance pattern alone does not describe where capture executes. ## Most common customer journey Most customers begin with direct SDK integration in Sandbox and adopt a customer-owned proxy before Production rollout. The journey below shows the typical path through the Resource Hub for a first-time customer team. ```text Quickstart │ ▼ Install and Configure Verify │ ▼ Direct SDK integration (Sandbox) │ ▼ First decision record │ ▼ Retrieve and verify │ ▼ Customer-owned proxy │ ▼ Production rollout ``` The journey is intentionally directional. Sandbox-first validation lowers integration risk; customer-owned proxy adoption before Production lowers governance risk. Mature teams can compress the loop, but the order above is the path most first-time customers follow. ## Customer-owned proxy pattern The Customer-Owned Proxy is the single most-discussed architectural component in any Production-bound Verify deployment, and it is consistently the most misunderstood. The proxy is not a runtime pattern — it is a governance pattern, and the distinction matters. The proxy sits between the customer runtime and the Verify API and evaluates capture and field-retention rules locally, inside the customer environment, before any record reaches Verify. Organizations adopt it not because they need additional infrastructure, but because they need capture decisions enforced on their side of the boundary. The deployment shape follows existing customer infrastructure standards rather than imposing new ones. AWS customers commonly deploy the proxy with CloudFormation or Terraform; non-AWS customers deploy with their existing infrastructure tooling. The architectural responsibilities are the same either way. In operation, the proxy holds the credential, evaluates the Capture Decision Policy (capture or skip), evaluates the Field Retention Policy (allow, drop, redact, truncate, or neverForward) on each retained field, and forwards only approved fields to the Verify API. The tradeoff is explicit and intentional: unauthorized fields never leave the customer environment, which means Verify never sees information the customer team did not approve for capture. > Verify is not a surveillance logger. Customers control what becomes a retained decision record. Verify does not determine what customer data is captured. ## Recommended pattern The recommended starting pattern is the one that lives closest to the runtime that already hosts the customer's AI-assisted workflow. Match capture placement to that runtime first, then layer queues or webhooks as the operational reality demands. > The pattern selected here is the integration shape for the Pilot and Production stages of the adoption maturity arc. For how integration choice fits into the broader Sandbox → Validation → Pilot → Production arc and the governance milestone each stage unlocks, see > [From Sandbox to Production](/resources/from-sandbox-to-production) . ### Selection guidance | Pattern | Best used when | Customer responsibility | Key risk to avoid | | --- | --- | --- | --- | | Backend service capture | An existing monolithic backend or microservice already hosts the AI-assisted workflow and can submit synchronously after output. | Hold the API key in the service's secret manager. Attach operational context before submission. Apply bounded retries with backoff. | Calling Verify from frontend or mobile code paths, or from any runtime outside the trusted server boundary. | | AWS Lambda capture | Stateless or event-driven AI-assisted workflows, scheduled jobs, or event-source triggers (API Gateway, EventBridge, SQS) drive the work. | Retrieve the API key from a secret store at cold start. Cache for the function's warm lifetime. Bound retries inside the function timeout. | Hardcoding secrets in environment variables committed to source control, or running unbounded retries that exceed the function timeout. | | Container / ECS capture | A long-running container service inside an existing ECS, Kubernetes, or equivalent cluster already hosts the workflow. | Inject the API key as a runtime secret at container start. Manage rolling deploys so capture continuity is preserved. Apply customer-side observability. | Baking secrets into image layers, or losing operational context during in-place container restarts. | | Queue-based capture | Capture should not block the customer-facing request path, or AI-assisted output is produced ahead of when capture should occur. | Preserve operational context across the queue boundary. Build the consumer as an idempotent worker. Confirm capture status via retrieval-by-context when uncertain. | Producing duplicate retained decision records on consumer restart, or losing operational context when re-enqueuing failed messages. | | Webhook notification | Downstream customer-side surfaces (review queues, case updates, audit preparation) need to react to Verify activity. | Operate the receiver as a customer-controlled endpoint. Acknowledge fast, queue for processing, and treat the payload as a signal — not the authoritative record. | Treating the webhook payload as the authoritative record, or running synchronous downstream work inside the request that should ACK quickly. | ## Which pattern should I choose? The framework above shows every valid combination of runtime and governance. The matrix below maps common customer goals to the recommended starting pattern, so a customer team can resolve the most frequent first-time questions without reading the page end-to-end. | Goal | Recommended pattern | | --- | --- | | Evaluate Verify | Direct SDK | | First Sandbox record | Direct SDK | | Internal tool | Direct SDK | | Production application | Customer-owned proxy | | Governance program | Customer-owned proxy | | Enterprise deployment | Customer-owned proxy | | AWS deployment | CloudFormation | | Infrastructure as code | Terraform | | Event-driven workflow | Lambda | | Long-running service | Container | | Asynchronous capture | Queue worker | ## AWS deployment options For AWS customers, the Customer-Owned Proxy can be deployed using one of two managed deployment artifacts: **CloudFormation** for AWS-native stack management, or **Terraform** for infrastructure-as-code standardized across providers. Both methods deploy the same components — an API Gateway, the Lambda proxy, the capture policy, and the Customer-Owned Capture Boundary that holds them together — and both implement the same architecture. CloudFormation tends to fit AWS-first teams who run console-driven deployments; Terraform tends to fit platform-engineering teams running infrastructure-as-code at scale across multiple environments. The architectural choice does not depend on the deployment artifact. For deployment topology, see: - [Reference Architecture: AWS — customer-side deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) ## How capture policies fit The Customer-Owned Proxy evaluates two independent governance layers inside the customer account. The Capture Decision Policy answers whether a workflow output should be retained, resolving each interaction to `capture` or `skip`. The Field Retention Policy answers which fields are permitted to leave the customer account, resolving each retained field to `allow`, `drop`, `redact`, `truncate`, or `neverForward`. Both layers run inside the customer-owned proxy. Operational context (`claimId`, `encounterId`, `transactionId`, `ticketId`, `escalationId`, and similar) is the retrieval surface and sits on its own field. Prompt and response are separate fields and may be subject to the field retention policy depending on deployment configuration; operational context typically remains allowed so the retrieval surface stays usable even when the body is retained sparsely. For the policy contract, file shape, evaluation order, and field retention outcomes, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## Real deployment examples The two examples below show how the pieces compose in customer-shaped workloads. Both use the customer-owned proxy because both represent governance-bound production shapes. ### Example: healthcare clinical review ```text Clinical Review Service │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy │ ▼ Field Retention Policy │ ▼ Verify API │ ▼ Decision Record │ ▼ Clinical Reviewer ``` Concrete fields captured on the retained decision record: - workflowId — clinical-summary-v1 or similar stable workflow identifier. - encounterId — the operational identifier the clinical reviewer already uses. - prompt — the input submitted to the model for the encounter summary. - response — the generated summary text returned by the model. - verification — the verification state the clinical reviewer relies on during chart review. ### Example: insurance claims review ```text Claims Service │ ▼ Customer-Owned Proxy │ ▼ Capture Policy │ ▼ Verify │ ▼ Decision Record │ ▼ Claims Reviewer ``` Concrete fields captured on the retained decision record: - claimId — the business identifier reviewers use to locate the case. - policyId — the customer-side identifier for the policy associated with the claim. - escalation decisions — the AI-assisted recommendation produced by the workflow (capture or skip). - retrieval later by claimId — reviewers retrieve the retained decision record by claim ID, not by internal IDs. > In both examples, capture decisions and field retention are evaluated inside the customer-owned proxy before any data is forwarded to Verify. The fields above are operational identifiers and content the customer team has chosen to retain. Sensitive or non-essential fields are dropped, redacted, truncated, or marked neverForward by the field retention policy. ## How it works Every pattern follows the same operational shape, even when the runtime that hosts the workflow differs. The customer runtime produces AI-assisted output and holds three things at the moment of capture: the workflowId that names the AI-assisted step, the output body the model returned, and the operational context the reviewer will use to retrieve the record later (claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId, or similar). The active environment — Sandbox or Production — is carried by the credential the runtime authenticates with. Authentication is environment-scoped. The runtime reads the Verify API key from the customer’s secret manager at process start (or at cold start, for Lambda), and uses that credential for every subsequent capture call. Sandbox keys read Sandbox secrets; Production keys read Production secrets. The credential never lives in source code, frontend artifacts, or shared environments. With those pieces in place, the runtime submits the retained decision record over HTTPS to the Verify Capture API. Verify returns a `decisionRecordId`, the retrieval keys derived from the operational context the customer attached, and the initial verification state. From that moment forward, the record is retrievable by either the `decisionRecordId` or any of the business identifiers the customer chose. Selected activity may emit a webhook event to a customer-owned receiver, which acknowledges the notification quickly, queues it for processing, and drives downstream surfaces such as review queues, case updates, or audit preparation. Months later, reviewers retrieve by the same operational context the runtime attached at capture time — the identifiers they already use day-to-day, not internal request or trace IDs. The differences across patterns live in the customer-side plumbing: how secrets are loaded, how retries are bounded, how operational context is propagated across queue or function boundaries, and how customer observability reports capture health. The shape of the record and the customer’s relationship with the Verify API are identical across every pattern. ## Customer responsibilities The customer team owns the runtime, the credentials, the operational context, the retry posture, the deployment discipline, and the downstream surfaces. Verify owns the public API and the retained decision record. The boundary between the two is the HTTPS call. On the runtime side, the customer chooses the pattern that matches an existing topology, holds the Verify API key in the customer secret manager (scoped per environment, never in source control or frontend artifacts), and operates retry behavior with bounded attempts, exponential backoff, and a stable retry key. Webhook receivers, when used, are customer-controlled endpoints with idempotent handling and fast acknowledgement. On the data side, the customer attaches stable, customer-recognizable operational context at capture time — the identifiers reviewers will use months later, not transient request or trace IDs — and keeps Sandbox and Production end-to-end separated across credentials, downstream surfaces, and observability. On the operational side, the customer maintains customer-side observability around capture and webhook health (without exposing credentials in log lines) and documents the chosen pattern in the customer’s internal runbook so the next engineer can onboard the same shape. ## Common mistakes The pitfalls below are the most common pattern-selection mistakes customer teams encounter during integration. Most are recoverable, but each one costs avoidable rework before Production rollout. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Choosing a pattern that does not match the existing runtime | Forcing Lambda capture into a workflow already hosted in a long-running container service adds runtime complexity without benefit. | Match capture placement to the runtime that already hosts the AI-assisted workflow. Add patterns only when operational reality demands them. | | Calling Verify from frontend or mobile code paths | Exposes API keys to untrusted runtimes and undermines the trust boundary the retained decision record depends on. | Frontend and mobile applications call the customer backend, which submits to Verify on their behalf using server-side credentials. | | Using a single API key across Sandbox and Production | Breaks the environment boundary the platform enforces; a single rotation impacts both environments and records can drift across them. | Distinct API keys per environment, distinct secret-manager paths, distinct downstream review surfaces. | | Treating webhook payloads as authoritative records | Webhook payloads are notifications. Acting on them as the system of record bypasses the retrieval surface designed for that purpose. | Treat webhook events as triggers. Retrieve by decisionRecordId or operational context to access the authoritative retained record. | | Running unbounded retries inside Lambda or sync request paths | Function timeouts truncate retry loops mid-attempt; upstream timeouts cascade into the request path. | Bound retries to fit within function timeout and request budget. Push longer retry horizons into queue-based capture instead. | | Losing operational context across the queue boundary | Workers that receive thin queue messages cannot reconstruct the operational context reviewers need for retrieval later. | Serialize workflowId and the operationalContext into the queue message itself. Treat the message shape as a contract. | | Composing patterns without documenting the customer-side architecture | When capture pattern, queue, and webhook receivers all run together, the next engineer on-call cannot reason about the integration without an internal runbook. | Document which patterns are composed, where each lives, and how they interact with operational context and environment scope. | ## Pattern selection mistakes The mistakes above are runtime-pattern decisions. The mistakes below are governance-pattern decisions — misalignments between the workload and the chosen governance posture. ### Choosing Lambda when a container already hosts the workflow Adds runtime complexity without benefit. If the customer already operates a long-running container service hosting the AI-assisted workflow, the simplest path is container capture from that same service. ### Deploying direct integration in a regulated workload Misses governance controls. Direct integration has no customer-owned capture boundary and no customer-owned policy enforcement. Regulated workloads should use the customer-owned proxy so capture decisions and field retention are enforced inside the customer account. ### Treating webhook payloads as authoritative records A webhook is a notification, not the system of record. Acting on the payload as authoritative bypasses the retrieval surface designed for that purpose. Treat webhook events as triggers and retrieve by decisionRecordId or operational context. ### Losing operational context across queues Breaks retrieval. Queue messages must preserve workflowId and operationalContext so the consumer can submit the retained decision record with the same identifiers reviewers will later use to find it. ### Using Sandbox and Production interchangeably Creates environment confusion. Sandbox and Production are isolated end-to-end — credentials, downstream review surfaces, observability, and capture data. Cross-environment usage breaks retrieval and is one of the most common sources of first-integration confusion. ## Pattern selection self-check Use the questions below to confirm the selected pattern is appropriate. If most answers are yes, the pattern is likely a good fit. If many answers are no, revisit the runtime and governance decisions before continuing. - Does the pattern already match where the AI-assisted workflow runs? - Can the runtime securely hold credentials (API keys, bearer tokens) from a customer-controlled secret store? - Can operational context (workflowId, claimId, encounterId, transactionId, ticketId, escalationId) be attached at capture time? - Can retries be managed safely with bounded backoff and idempotency? - Does the organization require governance controls over which workflow outputs become retained decision records? - Does the organization require customer-controlled retention decisions over which fields leave the customer account? > If the last two questions are answered yes, the integration should use the customer-owned proxy governance pattern regardless of which runtime pattern is selected. ## Validation checklist Before promoting any Verify integration from Sandbox to Production, both the runtime and governance decisions, and the resulting operational controls, should all be in place. ### Architecture decisions - Customer runtime pattern selected — backend service, AWS Lambda, container/ECS, or queue worker. - Governance pattern selected — direct integration or customer-owned proxy. - Environment separation confirmed — distinct Sandbox and Production credentials, runtimes, and downstream surfaces. - Capture policy reviewed — in governed deployments, the capture decision policy and field retention policy have been reviewed and signed off by the customer team. ### End-to-end validation - Record captured — capture call returns recorded with a decisionRecordId. - Record retrievable — retrieval by decisionRecordId and by operational context both succeed. - Record verified — verification on the captured record returns a verification result. - Logs contain metadata only — no prompts, responses, API keys, bearer tokens, secrets, or dropped fields appear in customer-side logs. - Dropped fields do not appear — fields removed by the field retention policy are not reaching the Verify API, the decision record, the Console, or evidence reports. ### Operational discipline - The chosen capture pattern (or composition) matches the runtime that already hosts the customer's AI-assisted workflow. - The customer backend, Lambda, container service, or queue worker holds the API key from a customer-controlled secret store — never from source code. - Operational context (workflowId plus stable business identifiers) is attached at capture time, regardless of pattern. - Retry behavior is bounded, backoff-aware, and idempotent across the chosen pattern. Duplicate retained decision records are prevented. - Webhook receivers (if used) are customer-controlled, idempotent, fast-ACK endpoints. They do not perform synchronous downstream work inside the request. - Customer-side observability is partitioned per environment and per pattern, so on-call engineers can tell where a failure originated. - The integration is documented in a customer-side runbook — which patterns are used, where each lives, and how the next engineer extends or operates them. ## Recommended next step Choose the next page based on what you are doing right now. Each link picks up exactly where this page leaves off. **If you have not yet integrated Verify → [Install and Configure Verify](/resources/install-and-configure-verify)** **If you need deployment guidance → [Reference Architecture: AWS](/resources/reference-architecture-aws)** **If you need governance guidance → [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy)** **If you are troubleshooting → [Troubleshooting Verify Integrations](/resources/troubleshooting-verify-integrations)** ## Related documentation Pair this hub with the following Tier-1 architecture pages and pattern-specific deep dives: - [Quickstart — first-time customer onboarding path.](/resources/quickstart) - [Install and Configure Verify — step-by-step setup, deployment-model selection, and Production readiness.](/resources/install-and-configure-verify) - [Configuring an AI Capture Policy — capture decision policy and field retention policy for customer-owned proxy deployments.](/resources/configuring-an-ai-capture-policy) - [Reference Architecture: AWS — customer-side deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) - [Server-Side Capture Pattern — the trust topology every pattern is built around.](/resources/server-side-capture-pattern) - [API Key Placement and Secret Storage — credential discipline that applies across all patterns.](/resources/api-key-placement-and-secret-storage) - [Environment Strategy — Sandbox vs Production discipline that every pattern must honor.](/resources/environment-strategy) - [Operational Context Mapping — retrieval keys customer teams attach at capture time.](/resources/operational-context-mapping) - [AWS Lambda Integration Pattern — deep dive on Lambda-based capture.](/resources/aws-lambda-integration-pattern) - [Container / ECS Integration Pattern — deep dive on container-based capture.](/resources/container-ecs-integration-pattern) - [Queue-Based Capture Pattern — deep dive on async, queue-fed capture.](/resources/queue-based-capture-pattern) - [Webhook Delivery Architecture — deep dive on receiving Verify notifications.](/resources/webhook-delivery-architecture) - [Network and HTTPS Egress — customer-side network expectations for all patterns.](/resources/network-and-https-egress) - [Troubleshooting Verify Integrations — symptom-first reference for SDK, API, Terraform, CloudFormation, capture policy, and Console issues.](/resources/troubleshooting-verify-integrations) --- --- title: Deployment Topology slug: deployment-topology category: Architecture retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/deployment-topology canonicalUrl: "https://obligra.ai/resources/deployment-topology" llmTags: - llm-aligned - architecture-core - canonical-concept-source - retrieval-tier-2 --- # Deployment Topology _Architecture_ _Where the customer establishes the capture boundary, how governance decisions run before transmission to Verify, and where retained decision records are managed afterwards._ ## 01. Overview AI-assisted workflows usually run inside existing customer environments. They live inside a backend service, an internal application, an API workflow, a serverless function, an orchestration layer, or an event-driven process — alongside the operational systems that already shape how the customer team operates. In practice, this is what makes deployment a question of integration rather than relocation. The most important deployment decision is not where Verify runs. Verify runs as a managed decision record platform outside the customer environment. The most important deployment decision is where the customer establishes the capture boundary inside their own infrastructure — and that decision sets the architectural posture for everything else the integration does. The boundary determines which interactions become decision records, which fields are permitted to leave the customer environment, and how governance is enforced before any data is transmitted to Verify. The tradeoff is intentional and symmetrical: the boundary is owned and operated by the customer, and Verify receives only the approved fields the boundary forwards. The rest of this page walks through that model. It introduces the customer-owned capture boundary, the direct and governed deployment patterns, the two policy layers that run inside the boundary (capture decision policy and field retention policy), and then the operational details — network, identity, retry behavior, scaling, environment separation, and security review — that follow from the boundary model. > Verify is a system of record for AI-assisted decisions. It is not a workflow engine, model provider, orchestration platform, or observability platform. The customer owns the workflow and the capture boundary. Obligra operates the managed decision record platform. ## 02. The customer-owned capture boundary The customer-owned capture boundary is the single most important concept in a Verify deployment. Organizations designing their first Production-grade deployment consistently discover that every other decision on this page — network path, identity model, data minimization, retry behavior, environment separation — sits downstream of where the boundary is drawn. Getting the boundary right early is the architectural decision the rest of the deployment rests on. The boundary operates inside customer infrastructure. The customer decides what becomes a decision record. The customer decides which fields may leave the customer environment. Governance decisions are evaluated before any data is transmitted to Verify. Verify receives only the approved fields the boundary forwards — which is what makes the boundary a governance component rather than a piece of infrastructure plumbing. The reasoning behind the design is worth being explicit about, because it shows up in audit conversations almost immediately. There are three reasons that build on each other. First, governance happens where the data lives. A reviewer asking “what was preserved and why?” should not have to inspect a remote service to answer that question. The policies that decided what to capture and which fields to retain run inside the customer environment, where the customer’s security, audit, and platform teams already have visibility. The customer can see, log, version, and review their own policy evaluations. Second, transmission is a customer-controlled event, not a background side effect of using an SDK. The customer-owned proxy is the component that physically forwards approved fields. Excluded fields never leave the customer account, never traverse a third-party network, and never appear in a Verify-side payload. The boundary is an explicit gate, not an implicit pipeline. Third, the customer is positioned to evolve their own policies without re-architecting the integration. New workflows, new regulatory constraints, and new sensitivity classes can be reflected in the policy without changing the Verify side of the contract. The boundary lets the customer own their governance posture over time. > Verify is not a surveillance logger. The customer-owned proxy and the policies that run inside it are the governance boundary. The customer decides what becomes a decision record and which fields are permitted to leave the environment. The remaining sections of this page describe two patterns for placing that boundary: a direct pattern used for early validation, and a governed pattern recommended for production. ![Inside the customer-owned capture boundary. Four components evaluated inside customer infrastructure, shown left to right inside a teal-bordered boundary frame. Component 01: Customer-Owned Proxy, a governance component the customer deploys and operates, receives the decision context from the application, evaluates the two policies, and forwards only approved fields to Verify, deployable via CloudFormation, Terraform, or customer infrastructure. Policy 01: Capture Decision Policy with the question 'Should this interaction become a decision record?' and two outcomes (Capture, Skip), with the note that not every AI interaction becomes a decision record. Policy 02: Field Retention Policy with the question 'Which fields may leave the customer environment?' and five actions (Allow, Redact, Truncate, Drop, Never Forward). Result: Approved Record Payload, shown in dark teal, listing the fields forwarded to Verify (prompt reference, response, claimId, transactionId, workflowId, validation state, environment metadata), with the note that approved fields only reach Verify and excluded fields stay inside the customer environment. Footer: only fields marked Allow reach Verify; redacted and truncated values are transformed first; dropped and Never-Forward fields never leave the customer environment.](/diagrams/obligra-verify-inside-capture-boundary.svg) * Inside the customer-owned capture boundary. Four components evaluated inside customer infrastructure: the proxy, the two policies, and the approved record payload that crosses the boundary. Subsequent sections cover each in detail. * ## Capture boundary vs proxy: how they relate Two terms in this documentation set are easy to conflate, and the conflation causes most of the confusion newer teams hit when they read across the Resource Hub. This section is the authoritative definitional anchor. > The Customer-Owned Capture Boundary is the architectural concept. The Customer-Owned Proxy is the implementation pattern most teams use to realize that concept. ![Capture Boundary vs Proxy: how they relate. A two-layer diagram showing the architectural concept on top and the implementation pattern below. Top layer, the architectural concept: the Customer-Owned Capture Boundary, a single rectangle representing the customer-side governance boundary where the customer evaluates Capture Decision Policy and Field Retention Policy before any data leaves the customer environment. Bottom layer, the implementation pattern: the Customer-Owned Proxy, a deployable service the customer runs that implements that boundary, with three labeled internal components, Capture Decision Policy evaluator, Field Retention Policy evaluator, and the approved-fields forwarder that physically transmits the approved record payload to the Verify API. A vertical mapping arrow connects the two layers with the labels ARCHITECTURAL CONCEPT on top and IMPLEMENTATION PATTERN below. Footer callout: The Customer-Owned Capture Boundary is the concept. The Customer-Owned Proxy is the most common implementation of that concept.](/diagrams/obligra-verify-capture-boundary-vs-proxy.svg) * Two layers of the same idea. The boundary is the concept every customer must reason about; the proxy is the concrete service most customers deploy to realize it. * ### Customer-Owned Capture Boundary — the architectural concept The Customer-Owned Capture Boundary is the customer-side boundary where the customer decides what becomes a decision record and which fields may leave the customer environment. It is an architectural concept, not a product or a piece of infrastructure: it is the place where governance runs before any data is transmitted to Verify. The boundary carries two responsibilities. The Capture Decision Policy decides whether an interaction becomes a decision record. The Field Retention Policy decides which fields may leave the customer environment. Both decisions are evaluated inside customer infrastructure, by code the customer owns and operates, before the approved record payload crosses the boundary. ### Customer-Owned Proxy — the implementation pattern The Customer-Owned Proxy is the deployable service the customer runs to implement the boundary. It is delivered as a CloudFormation template, a Terraform module, or as customer-provisioned infrastructure, and it lives inside the customer environment alongside the application that produces the AI-assisted decision. Inside the proxy, the two policies are evaluated and the approved-fields forwarder physically transmits the approved record payload to the Verify API. The proxy is the most common way customers realize the boundary in production, but it is not the only conceivable implementation. The relationship is one of concept to pattern, not concept to product. ### How to read these terms across the Resource Hub When the documentation talks about *where governance runs*, who owns the governance posture, or what crosses the customer environment, it is talking about the Customer-Owned Capture Boundary — the concept. When the documentation talks about *what gets deployed*, which service evaluates the policies, or how the forwarding service is provisioned, it is talking about the Customer-Owned Proxy — the implementation. The two terms are related, but they are not interchangeable, and using them precisely keeps the Resource Hub navigable for both architects and operators. For a standalone summary suitable for cross-linking from other pages, see [Capture Boundary vs Proxy](/resources/capture-boundary-vs-proxy) . ## 03. Direct vs governed deployments Verify supports two deployment patterns. Both reach the same Verify API and produce the same retained decision records. The difference is where capture decisions and field retention are enforced — and therefore who owns the governance posture for that workflow. ### Direct deployment In a direct deployment, the customer application calls the Verify API without a customer-owned proxy or policy layer in between. The application itself decides whether to capture and which fields to forward. ```text Customer Application │ ▼ Verify API │ ▼ Managed Decision Record Platform ``` Direct deployment is appropriate for early-stage and non-production use: - Sandbox - Builder - Internal testing - Evaluation - Proof of concept It is the fastest path to a working capture loop. It is also the right pattern for a single developer validating the end-to-end flow before involving security, platform, or governance teams. Direct deployment is the shortest distance between an idea and a retained decision record sitting in the Verify Console. What direct deployment does not give you is a customer-owned governance boundary. There is no separate policy component inside the customer environment that can be reviewed by security, no separate forwarder that can be audited, and no dedicated place for capture decisions and field retention rules to live. The application code itself is the boundary. That is acceptable for evaluation. It is not the recommended shape for production workloads. ### Governed deployment In a governed deployment, the customer application calls a customer-owned proxy. The proxy evaluates a capture decision policy and a field retention policy. Only approved fields are forwarded to the Verify API. ```text Customer Application │ ▼ Customer Runtime │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy (capture / skip) │ ▼ Field Retention Policy (allow / drop / redact / truncate / neverForward) │ ▼ Approved Fields Only │ ▼ Verify API │ ▼ Managed Decision Record Platform ``` Governed deployment is the recommended production pattern. It is appropriate for: - Production - Enterprise - Regulated workloads - Governance-sensitive environments The reason governance teams adopt this pattern is that the policy decisions are physically separated from the application code. Application engineers do not have to implement, maintain, or review redaction logic inline. The policy lives in one place, is version-controlled, and is subject to the customer’s normal change-management and audit processes. Field retention is enforced before transmission, so excluded fields never leave the customer account regardless of what application code happens to pass to the SDK. ### Why most customers begin with direct Most customers begin with a direct deployment in Sandbox. They wire up the SDK, submit a first decision record, and confirm that retrieval and verification work end-to-end. The loop is short, the feedback is immediate, and the team learns the record model without committing to infrastructure they have not validated yet. Once the team understands the record model and is preparing for production rollout, they introduce a customer-owned proxy and move policy evaluation into it. The Sandbox integration usually stays in direct mode for builder and evaluation workflows. The production rollout uses the governed pattern. Both can coexist indefinitely; they serve different audiences and different stages. ## 04. Capture decision policy The capture decision policy answers one question: > Should this interaction become a decision record? Not every AI interaction needs to become a retained decision record. The signal Verify is designed to preserve is AI-assisted operational decisions — outputs that affect a workflow, a person, an account, a claim, a transaction, or any other operational artifact a reviewer might later need to evaluate. Speculative drafts, internal scratch generations, throwaway completions during prompt tuning, and exploratory queries that never affect a real workflow generally do not belong in the decision record corpus. Storing them dilutes the retrieval surface and makes it harder for reviewers to find the records that actually matter. The capture decision policy is how the customer makes that determination consistently and reviewably, in one place, across every workflow that calls into the proxy. The policy has two possible outcomes: - capture - skip Common workflows where the answer is almost always **capture**: - Human approval events - Claim determinations - Escalations - Risk decisions - Compliance reviews - Customer-impacting routing decisions - Final-state workflow transitions - Reviewer-facing recommendations Common workflows where the answer is often **skip**: - Internal prompt experimentation - Draft completions never shown to a person - Background warm-up calls - Smoke tests and synthetic traffic - Low-signal exploratory queries The capture decision is a policy expression, not a code branch buried inside an application. Centralizing it means the policy can be reviewed by the customer’s compliance and security teams alongside other governance artifacts, and updated independently of the workflow code. ## 05. Field retention policy The field retention policy answers a second question: > Which fields are permitted to leave the customer environment? Capturing a decision record does not mean forwarding every field that was present at the moment of capture. Reviewers downstream usually need a small, stable set of operational identifiers, structured metadata about the AI step, and the decision context that actually matters to the workflow. Everything else stays in the customer’s authoritative systems. The field retention policy enforces that boundary field-by-field. It has five possible outcomes: | Outcome | What it means | | --- | --- | | allow | The field is forwarded to Verify unchanged. Use for stable operational identifiers and non-sensitive workflow metadata. | | drop | The field is removed entirely before transmission. Use for fields that are not needed for review. | | redact | The field is replaced with a redaction token or masked value before transmission. Use when the existence of the field matters but its value should not leave the environment. | | truncate | The field is shortened to a configured length before transmission. Use to bound large free-text or prompt-style payloads. | | neverForward | The field is treated as ineligible for transmission under any condition. Use for the most sensitive classes of data the customer does not want to leave the environment, ever. | Stable operational identifiers are typically the right shape for **allow** outcomes because reviewers will retrieve records by those identifiers months later. Examples include: - claimId - ticketId - transactionId - encounterId - customerReference - workflowId - reviewCaseId - escalationId Free-text prompt payloads, raw customer documents, full model outputs, and any field that carries sensitive customer content are typical candidates for **redact**, **truncate** , or **neverForward** outcomes, depending on the customer’s sensitivity posture and regulatory environment. Both the capture decision policy and the field retention policy are evaluated inside the customer-owned proxy. They are configured by the customer, reviewable by the customer’s security and compliance teams, and versioned alongside other governance artifacts. For the policy file shape, evaluation order, and operational semantics, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## 06. Standard deployment model With the boundary, the deployment patterns, and the two policy layers established, the standard deployment model becomes straightforward: it is the physical manifestation of the governed pattern inside a customer cloud account, with the Verify managed platform sitting outside that account. The model has three zones: the customer cloud account, the customer-owned capture boundary that lives inside that account, and the Obligra Verify managed platform that lives outside it. ### Customer cloud account The customer cloud account contains the workload that creates or uses an AI-assisted output, together with the customer-owned capture boundary that governs what leaves the environment. The account typically contains: - application or workflow runtime - API service or backend service - workflow orchestrator - model invocation path - Verify SDK or API client - customer-owned proxy - capture decision policy - field retention policy - customer data and context sources - IAM roles and execution identities - secrets and configuration management - VPC, subnet, and egress controls - application logs, traces, SIEM, and operational tooling The customer controls the workflow, the capture point, the proxy, and the policies. Approved fields leave the environment through a single outbound integration boundary. ### Obligra Verify managed platform The Obligra Verify managed platform receives approved fields and operates the retained decision record service. At the capability level, the platform provides: - Verify API - Managed Decision Record Platform - Retention - Retrieval - Verification - Evidence - Verify Console - Managed availability This separation helps customers integrate Verify without giving Obligra inbound access to the customer environment, and without exposing internal platform implementation details to the customer side. ![Reference Architecture for Obligra Verify on AWS. A three-zone horizontal topology. Zone 1 Customer AWS Account on the left contains the Application and Workflow Runtime, Customer Data Sources, and Identity and Secrets. Zone 2 Customer-Owned Capture Boundary in the middle is the hero zone and contains the Verify SDK, the Customer-Owned Proxy deployable via CloudFormation, Terraform, or customer-managed infrastructure, the Capture Decision Policy that evaluates capture or skip outcomes, the Field Retention Policy that applies allow, drop, redact, truncate, or never-forward actions, and the Approved Fields Only gate that ensures only approved data exits the customer environment. Zone 3 Obligra Verify Managed Platform on the right contains the Verify API, the Managed Decision Record Platform handling retention, retrieval, verification, and evidence, and the Verify Console used by operations, compliance, audit, legal, risk, and review teams.](/diagrams/obligra-verify-reference-architecture-aws.svg) * Customer-Owned Capture Boundary Architecture for Obligra Verify. Customers own the capture boundary, capture policy, and governance controls. Obligra operates the managed decision record platform for retention, retrieval, verification, evidence, and review. * ## 07. What the customer deploys The customer deploys the workload that owns the AI-assisted decision flow, plus the components that make up the capture boundary. The workload itself may be a backend service, API handler, serverless function, workflow orchestrator, batch process, or internal application service. The boundary components are the same regardless of which workload shape is used. The customer environment typically includes: - application runtime - AI workflow code - Verify SDK or API client - model or provider integration - customer-owned proxy - capture decision policy configuration - field retention policy configuration - customer data sources - IAM role or execution identity - secret or configuration store - outbound network access - application logs and monitoring The SDK should be treated as part of the application integration layer. It does not replace the model provider, application workflow, business logic, observability tools, or security tooling. The customer-owned proxy is a governance component, not a transport component — its job is to evaluate the policies, not to add unrelated processing to the workflow. Verify does not require the customer to change model providers. The customer can continue using Amazon Bedrock, a hosted model, an internal model endpoint, or an external LLM provider. Verify receives the approved fields after the policies have evaluated the captured decision context. ## 08. What Obligra operates Obligra operates the managed decision record platform that receives approved fields and manages retained decision records. The platform is described at a capability level so customers can reason about what it does without depending on internal implementation details. The managed platform is responsible for: - receiving approved fields submitted by customer-owned proxies and direct integrations - validating required record fields - creating retained decision records - associating records with tenant, workflow, and environment metadata - supporting retrieval by operational context - supporting verification on retrieval - applying configured retention behavior - exposing the Verify Console and API access for review workflows - supporting evidence generation for compliance, audit, legal, risk, and operations review This document intentionally describes the platform at a capability level. It does not expose internal storage, indexing, retrieval, tenancy, or orchestration implementation details. ## 09. Standard integration flow A typical governed integration follows this sequence. The steps are intentionally written so the policy evaluation steps are visible — they are the most important steps, not implementation detail to be hidden. 1. A customer workflow receives a business input. 2. The workflow prepares context for an AI-assisted step. 3. The workflow invokes the model or provider selected by the customer. 4. The workflow receives an AI output. 5. The application passes the decision context to the Verify SDK or API client, which delivers it to the customer-owned proxy. 6. The customer-owned proxy evaluates the capture decision policy. The outcome is capture or skip. 7. If the outcome is capture, the proxy evaluates the field retention policy. Each field is resolved to allow, drop, redact, truncate, or neverForward. 8. The proxy assembles the approved fields and forwards them to the Verify API. 9. Verify validates the structure and creates a retained decision record. 10. The customer receives a decision record ID or capture response. 11. The record can later be retrieved, inspected, and verified through the Verify Console or API. The capture step should occur at the point where the workflow has enough information to preserve the decision context. That usually means after the AI output has been generated and before or immediately after the output influences a downstream workflow action. In a direct deployment, steps 6 and 7 collapse: there is no customer-owned proxy and no policy layer between the SDK and the Verify API. That makes direct deployment the right shape for evaluation and builder use, and the wrong shape for production workloads where governance and field retention need to be enforced consistently. ![Verify capture integration sequence shown as a horizontal flow of six stages from business event to verified record. Stage 01 Business Event: a workflow trigger originates inside the customer environment. Stage 02 Customer Workflow: the application invokes the AI-assisted step and prepares decision context. Stage 03 Customer-Owned Capture Boundary, the governance hero of the sequence: capture and field retention decisions are evaluated inside customer infrastructure. An outbound HTTPS arrow crosses the ownership boundary. Stage 04 Verify API: receives only approved fields, no inbound access to the customer environment. Stage 05 Managed Decision Record Platform: capabilities for Retention, Retrieval, Verification, and Evidence. Stage 06 Retrieve & Verify Later: authorized reviewers retrieve records by operational context. Below the cards, an ownership band shows stages 01-03 as Customer-Operated (workflow runs inside the customer environment; governance is enforced before transmission) and stages 04-06 as Obligra-Operated (Verify retains, retrieves, verifies, and generates evidence for authorized reviewers). Footer caption: customer owns the capture boundary; Obligra owns the decision record platform.](/diagrams/obligra-verify-capture-sequence.svg) * Verify capture integration sequence. Six stages from business event to verified record. The customer environment owns stages 1–3 and enforces governance before transmission. Obligra operates stages 4–6 as the managed decision record platform. * ## 10. Network path and connectivity In the standard deployment topology, the customer-owned proxy (or the application, in direct deployments) initiates outbound HTTPS requests to the Verify API. The integration does not require inbound access from Obligra into the customer environment. Customer teams should review: - egress path from workload subnets - NAT gateway, egress proxy, or firewall rules - DNS resolution - TLS inspection policy, if used - allowlisted API endpoints - timeout behavior - retry behavior - failure handling if capture is temporarily unavailable The capture path should be designed as an outbound integration from the customer-owned proxy to the Verify managed platform. For production deployments, teams should confirm that network controls allow the specific runtime component that performs forwarding to reach the Verify endpoint. Other workloads should not receive unnecessary access. Security teams should treat the Verify endpoint as an approved outbound integration endpoint and scope access to the workload components that perform forwarding. ## 11. Identity and access model The component that forwards approved fields to Verify — the customer-owned proxy in governed deployments, or the application itself in direct deployments — should call Verify using a scoped integration credential or workload-specific API credential. The credential should be stored in the customer’s secret management system and exposed only to that component. Customer teams should define: - which workloads may create decision records - which environments may write to which tenant or workspace - which users may retrieve or review records - which roles may change retention or verification-related settings - how credentials are rotated - how access is revoked when a workload is decommissioned For cloud deployments, customers typically manage runtime identity through their cloud-native IAM, execution roles, secrets management, and deployment pipelines. Verify does not require broad access to the customer cloud account. The integration should follow least-privilege design. The application component that creates a record should have only the permissions required to submit capture requests for the intended tenant, workflow, and environment. ## 12. Data boundary and payload minimization The customer controls what decision context is submitted to Verify. In a governed deployment, that control is encoded in the field retention policy. In a direct deployment, it is encoded in application code. Either way, the capture payload should include enough context to make the AI-assisted decision reviewable later, but should not include unnecessary sensitive data. Customer teams should make explicit decisions for: - prompt or input content - generated output - retrieved context references - workflow metadata - operational identifiers - validation result - reviewer state - model/provider metadata - redaction or tokenization requirements - fields excluded from capture The deployment topology should be paired with a written capture policy that defines what is retained, what is redacted, and what remains only in the customer’s authoritative source systems. This is especially important in healthcare, financial services, insurance, and other regulated workflows where the record must be useful for later review without collecting unnecessary data. The capture policy should be reviewed with security, compliance, and business owners before production use. ## 13. Environment separation Customers should separate Verify capture configuration by environment. Development, staging, and production workloads should use separate configuration values, credentials, workflows, and retention settings. In governed deployments, each environment runs its own proxy with its own policy configuration. A production deployment should avoid mixing test records and production records in the same workflow namespace. Recommended environment metadata includes: - tenant or organization ID - environment name - application name - workflow ID - model/provider version - release version - region - Verify SDK version Environment separation helps teams test capture behavior without polluting production review surfaces. It also helps compliance and audit teams distinguish production decision records from development or staging activity. Production records should be separated from test records because retrieval, retention, and review workflows may have different operational and compliance requirements. ## 14. Deployment patterns Different workflows need different capture patterns. The pattern should match the risk level, latency requirement, and availability requirement of the workflow. ![Deployment pattern selection: five architecture cards comparing deployment patterns for integrating Verify into AI-assisted workflows. Pattern 01 Direct Synchronous Capture with vertical flow Business Event → Workflow → Customer-Owned Capture Boundary → Verify → Continue Workflow; best fit high-risk workflows, decisions required before workflow proceeds, human review checkpoints, regulatory workflows; tradeoffs add capture dependency, add latency, require availability planning; failure behavior workflow may pause, fail-closed possible, manual review. Pattern 02 Asynchronous Capture with flow Business Event → Workflow → Background Capture Worker → Customer-Owned Capture Boundary → Verify; best fit user-facing experiences, high-volume workloads, non-blocking workflows; tradeoffs require monitoring, require reconciliation, additional operational complexity; failure behavior workflow proceeds, capture retried with alerts generated. Pattern 03 Buffered Capture with flow Business Event → Workflow → Customer Queue → Customer-Owned Capture Boundary → Verify; best fit large-scale workloads, high throughput environments, availability-sensitive systems; tradeoffs queue management, replay strategy, dead-letter handling; failure behavior events retained with replay available, capture resumes after recovery. Pattern 04 Batch Capture with flow Workflow Activity → Batch Collection → Customer-Owned Capture Boundary → Verify; best fit periodic review workflows, back-office processing, lower urgency capture; tradeoffs delayed visibility, delayed retrieval availability; failure behavior batch rerun with retry processing, exception reporting. Pattern 05 Private Connectivity with flow Customer Environment → Private Connectivity → Verify; best fit enterprise environments, specialized networking requirements, customer-specific deployments; tradeoffs additional onboarding, additional planning, customer-specific implementation; failure behavior follows customer-defined networking and routing strategy. Three callouts below the cards reinforce: pattern selection should match workload risk (high-risk workflows favor synchronous or fail-closed capture, high-volume workloads favor asynchronous, buffered, or queue-backed patterns); governance applies to every pattern (Capture Decision Policy and Field Retention Policy are evaluated inside the customer-owned capture boundary before approved fields reach Verify); operational controls every production pattern must define (retry, timeout, idempotency, alerting, replay, dead-letter handling — part of the customer-operated capture boundary).](/diagrams/obligra-verify-deployment-patterns.svg) * Five common deployment patterns for integrating Verify into AI-assisted workflows. Pattern selection should match workload risk, latency tolerance, and availability requirements. Every production pattern places capture controls inside the Customer-Owned Capture Boundary so governance is enforced before transmission to Verify. * High-risk workflows may require blocking or fail-closed capture so the workflow does not proceed unless a retained decision record is created. Lower-risk or high-volume workflows may use asynchronous or buffered capture with monitoring, retry, and replay. Where the matrix references a private connectivity pattern, treat it as a customer-specific option that may be supported for enterprise environments with stricter network requirements. It should not be assumed to be generally available without confirmation from Obligra. All patterns should define timeout behavior, retry policy, idempotency strategy, alerting, and dead-letter handling before production deployment. In governed deployments, these behaviors live in the customer-owned proxy alongside the policies. ## 15. Retry, buffering, and failure handling Capture failure should not create ambiguity in production workflows. Customer teams should decide whether capture is synchronous, asynchronous, blocking, or non-blocking for each workflow. ### Blocking capture Blocking capture is appropriate when a retained decision record is required before the workflow can proceed. Examples include: - regulated review - high-risk decision - formal approval workflow - legal or audit-sensitive workflow If capture fails, the workflow may pause, fail closed, or route to manual review. ### Non-blocking capture Non-blocking capture is appropriate when the workflow can proceed even if capture is delayed. Examples include: - low-risk summary - operational assistant response - internal workflow note - low-impact recommendation If capture fails, the workflow proceeds while retry, alerting, or reconciliation runs separately. ### Buffered capture Buffered capture is appropriate when capture events should be queued locally or through customer-operated infrastructure before submission. Examples include: - temporary network failure - high-volume workloads - batch processing - strict availability requirements Customer teams should define: - retry count - retry backoff strategy - timeout values - queue or buffer location - dead-letter behavior - alerting threshold - replay process - duplicate submission behavior - idempotency key strategy Capture requests should use an idempotency strategy so retries do not create duplicate retained decision records for the same workflow event. The failure policy should match the business importance of the retained decision record. ## 16. Scaling considerations Scaling depends on decision volume, record size, capture timing, and workflow concurrency. In governed deployments, customer teams should also size the customer-owned proxy for the same dimensions. Customer teams should estimate: - records per day - peak records per minute - average capture payload size - maximum capture payload size - synchronous vs asynchronous capture ratio - retry volume during partial outages - retention duration - retrieval frequency - review and export patterns For high-throughput workloads, capture should usually be decoupled from user-facing execution through asynchronous submission, queueing, or worker-based forwarding. For low-volume but high-risk workflows, synchronous capture may be acceptable if the workflow requires a retained decision record before proceeding. Teams should evaluate latency, throughput, availability, and review requirements before selecting the deployment pattern. Capture volume should be estimated separately from model invocation volume because not every model response necessarily becomes a retained decision record — that determination is made by the capture decision policy. ## 17. Industry deployment examples Deployment topology should reflect the workflow that creates the AI-assisted decision. The shape of the customer-owned proxy and the policies inside it changes based on which identifiers reviewers will need months later. ### Healthcare and telehealth A telehealth platform may place the Verify SDK in the backend service that creates AI-assisted visit summaries, triage recommendations, intake summaries, or care workflow notes. The customer-owned proxy enforces capture decisions (for example, only finalized summaries are captured) and field retention (for example, raw transcripts are dropped or truncated while encounter identifiers are allowed through). The approved capture payload should include: - encounter ID - visit ID - clinician workflow - generated summary ID - validation state - review state - verification state - model/provider metadata This gives clinical operations, compliance, and audit teams a retained record that can be retrieved later by operational context. ### Banking and financial services A financial services workflow may capture records from fraud review, dispute intake, transaction classification, or escalation routing services. The customer-owned proxy enforces capture decisions (only reviewer-impacting events become records) and field retention (account numbers are typically redacted while transaction and case identifiers are allowed). The approved capture payload should include: - transaction ID - account reference - case ID - dispute ID - workflow state - model/provider metadata - validation result - verification state This gives fraud, compliance, legal, and risk teams a retained record tied to the transaction or case under review. ### Insurance An insurance workflow may capture records from claims intake, coverage routing, appeal review, or underwriting support. The customer-owned proxy enforces capture decisions (only review-relevant claim events become records) and field retention (sensitive applicant content is typically redacted or dropped while claim, policy, and appeal identifiers are allowed). The approved capture payload should include: - claim ID - policy ID - coverage workflow - routing decision - appeal state - reviewer state - validation result - verification state This gives claims, coverage, legal, and audit teams a retained record connected to the operational workflow where the AI-assisted decision occurred. ## 18. Security review checklist A secure Verify deployment is not defined by infrastructure alone. It is defined by governance decisions: which interactions become decision records, which fields are permitted to leave the customer environment, who may retrieve records after capture, and how those decisions are reviewed and updated over time. The checklist below covers both layers — the infrastructure controls a security team would normally inspect, and the governance controls that distinguish a well-deployed Verify integration from a hastily-wired one. It should be reviewed by application owners, platform engineering, security, compliance, and any team responsible for the workflow being captured. Before production deployment, customer teams should review: - Which workflows create decision records? - Is capture decision policy configured for each workflow? - Are capture and skip outcomes correct for each workflow? - Which fields are captured? - Which fields are dropped, redacted, truncated, or never forwarded? - Is the field retention policy reviewed and versioned? - Is the customer-owned proxy deployed for production workloads? - Which runtime identity submits records? - Where are credentials stored? - How are credentials rotated? - What outbound endpoint is allowed? - Is capture blocking or non-blocking? - What happens when capture fails? - Are retries idempotent? - How are failed captures alerted? - Who can retrieve records? - Who can verify records? - Who can change retention settings? - Are development, staging, and production separated, with separate proxy policies? - Are industry-specific identifiers captured consistently? ## 19. Operational responsibilities The customer and Obligra operate different parts of the topology. The shared responsibility model below reflects the customer-owned capture boundary — the customer owns the proxy and the policies that run inside it, and Obligra owns the managed decision record platform and the surfaces that expose retained records to authorized reviewers. ### Customer responsibilities The customer is responsible for: - selecting the workflow capture point - deploying and operating the customer-owned proxy in production - configuring and maintaining the capture decision policy - configuring and maintaining the field retention policy - redaction logic and field-level governance - managing runtime identity and secrets - managing outbound network access - operational context selection — choosing the identifiers reviewers will rely on later - workflow integration — placing the Verify SDK or API client at the right point in the workflow - handling retry, buffering, and failure policy - maintaining customer application logs and monitoring - ensuring industry-specific identifiers are passed consistently - determining how retrieved records are used in business review ### Obligra responsibilities Obligra is responsible for: - operating the Verify API - operating the Managed Decision Record Platform - decision record retention - retrieval services - verification services - evidence generation - Verify Console access for authorized reviewers - managed availability of the platform surfaces This responsibility split keeps the customer’s workload, data sources, and governance decisions under customer control while letting Verify manage the retained decision record platform. ## 20. What this topology does not require The standard deployment topology is intentionally narrow in what it asks of the customer. It is worth being explicit about that, because evaluation teams and security reviewers often arrive expecting a heavier integration than Verify actually requires. Verify does not assume access to systems the customer has not chosen to share. It does not replace customer infrastructure the customer already operates. And it does not require the customer to move workflow data into the Verify environment in order to retain decision records. Specifically, the topology does not require: - Obligra access to raw source systems - Obligra access to customer databases - Obligra access to all prompts - Obligra access to all responses - inbound access from Obligra into the customer cloud account - replacement of the customer's model provider - replacement of the customer's observability tooling - replacement of customer IAM - changes to customer networking architecture - movement of entire workflow payloads into Verify - broad access to customer databases or source systems - capture of unnecessary sensitive fields The customer remains in control of what is captured, what is forwarded, and which authorized reviewers can retrieve records afterwards. Verify is positioned as a managed decision record platform behind a customer-owned governance boundary, not as a deeper integration into the customer’s data plane. ## 21. Key architecture principle A reader who has worked through this page should leave with four things resolved. **Why deployment topology matters.** Topology is the place where governance, security, and review obligations become concrete. The boundary you draw determines what your reviewers can see, what your security team can audit, and which data ever leaves the customer environment. **Why governance happens before transmission.** A policy that runs after data has already left the customer environment is not really a governance policy. Capture decision policy and field retention policy are designed to run inside the customer-owned proxy, so excluded fields never leave the environment in the first place. **Why production customers adopt the customer-owned proxy pattern.** The proxy gives the customer’s governance posture a place to live. Policies are version-controlled, reviewable, and updatable independently of workflow code. The application no longer has to carry redaction logic inline. Security review has a clear artifact to inspect. **How Verify fits into the customer’s architecture.** Verify is a system of record for AI-assisted decisions. It is not a workflow engine, model provider, orchestration platform, or observability platform. It receives approved fields, retains them as decision records, and exposes them for retrieval, verification, evidence generation, and review — with the customer always upstream of that boundary. > The most important deployment decision is not where Verify runs. The most important deployment decision is where you draw your capture boundary. --- --- title: Evidence vs. Logs slug: evidence-vs-logs category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/evidence-vs-logs canonicalUrl: "https://obligra.ai/resources/evidence-vs-logs" llmTags: - llm-aligned - canonical-concept - canonical-concept-source - retrieval-tier-2 --- # Evidence vs. Logs _Fundamentals_ _An organization with comprehensive logging can still find itself unable to answer the review questions an AI-assisted workflow generates. Logs describe what a service did. Decision evidence preserves the state of an AI-assisted decision. They are different artifacts, they answer different questions, and the gap between them is what drives most after-the-fact review pain. The most important shift is recognizing that logs are operational and decision evidence is reviewable — logs help teams operate the system, decision evidence helps teams review the decision._ ## 01. Overview An organization can ship a fully observable AI-assisted workflow — structured logs, distributed tracing, metrics, dashboards, alerts — and still find itself unable to answer the review questions that come back from compliance, audit, fraud, dispute response, clinical review, or legal. The observability stack works exactly as designed. It just was not designed for the question being asked. Logs are records of system activity. Decision evidence is the retained record of an AI-assisted decision. Both matter. They are not interchangeable. > Logs describe activity. Decision evidence preserves the state of a decision. ![Logs vs Decision Evidence. A side-by-side visual that contrasts the two artifacts. Left column, Logs: a system-activity record emitted by the runtime as a side effect of execution, with example fields shown as small chips including timestamp, service name, request ID, trace ID, status code, latency, error message, and retry behavior; footer notes that logs describe what a service did and are scoped to individual components. Right column, Decision Evidence: a preserved decision artifact captured at execution time, with the field families shown as larger labeled rows including Input, Retrieved Context, Prompt or Request Structure, Model Execution Metadata, Output, Validation State, Operational Identifiers, Integrity Metadata, and Retention Metadata; footer notes that decision evidence preserves the state of an AI-assisted decision for later retrieval, review, and verification. Bottom callout: Logs describe activity. Decision evidence preserves the state of a decision.](/diagrams/obligra-verify-logs-vs-decision-evidence.svg) * Two artifacts, two purposes. The fields on the left describe what the system did. The fields on the right preserve what was decided. * The rest of this page walks the distinction in turn — what each artifact is for, why AI-assisted workflows specifically need decision evidence, the questions each artifact answers, what a retained record preserves, and where this matters in production. ## 02. What each artifact is for Logs and decision evidence are not graded on a quality axis. They exist for different reasons. ### Logs Logs are emitted by systems, services, applications, infrastructure components, and third-party tools as a side effect of execution. They describe what happened inside a runtime — that a request reached a service, that an endpoint returned a status code, that a retry was triggered, that a workflow advanced. Engineering and operations teams use them to run reliable systems, diagnose failures, and investigate incidents in real time. They are necessary for operations. ### Decision evidence Decision evidence is the retained record of an AI-assisted decision. It is captured at execution time as a structured artifact and is designed to be readable by a reviewer arriving later. It preserves the input the workflow received, the context that shaped the output, how the model was instructed, what was produced, what controls applied, which workflow the decision belonged to, and whether the retained record still verifies. It is necessary for review. Both are valuable. Both should exist. The question is which one a team reaches for when a decision is questioned weeks or months after the workflow ran. ## 03. Why AI-assisted workflows need decision evidence Traditional software systems are usually easier to review after the fact. A request enters the system, rules execute, data is written, and the logic path can often be inspected later because the rules themselves did not change while the system ran. AI-assisted workflows do not behave that way. A generated output may depend on a prompt template, retrieved context, a model provider, a model version, runtime parameters, validation logic, and workflow state that all existed only at execution time. Weeks later, the prompt template may have moved on, the model may have been swapped, the retrieved context may return different results, and the workflow may only retain its final state. The conditions that produced the original output have been overwritten by the system continuing to run. That is the gap decision evidence closes. A retained decision record preserves the original AI-assisted moment as a structured artifact, not as a set of inferences stitched together from logs that have since rolled over. The reviewer arriving later inspects the record that was captured, not a reconstruction. ## 04. Two questions, two artifacts Logs and decision evidence answer different questions. A team that asks an operational question of a logging system gets a useful answer. A team that asks a review question of a logging system gets a partial answer at best. ![Two questions, two artifacts. A side-by-side visual showing that operational questions and review questions are answered by different artifacts. Left column, Operational Questions: did the request reach the service, did the model return a response, was there a timeout, was a retry triggered, did the workflow advance. These questions are answered by Logs, the system-activity record. Right column, Review Questions: what decision was made, what input was used, what context influenced the output, which workflow did the decision belong to, can the retained record still be verified. These questions are answered by Decision Evidence, the retained decision record. Bottom callout: An organization that conflates the two artifacts ends up trying to answer review questions with logs.](/diagrams/obligra-verify-two-questions-two-artifacts.svg) * Operational and review questions surface at different times, in different conversations, with different teams. The artifacts that answer them are different. * Operational questions are the ones engineering and operations teams ask while the system runs: did the request reach the service, did the endpoint return a response, was there a timeout, was a retry triggered, did the workflow advance. Logs are designed to answer those questions cleanly. Review questions are different in shape and in audience. A compliance officer asks what decision was made and what input shaped it. An auditor asks which workflow the decision belonged to and whether the retained record still matches what was captured. A clinical reviewer asks what context was used and what was generated. A legal team asks whether the artifact under review is the original. None of those questions is best served by a log query — they are served by a retained record. ## 05. What decision evidence preserves The shape of decision evidence is determined by the questions reviewers actually ask. A retained decision record is structured around five field families, each answering a recurring review question without forcing the reviewer to leave the artifact. ![What Decision Evidence Preserves. A grouped visual showing the field families of a retained decision record organized by the question each group answers. Group 01 What the workflow saw: Input, Retrieved Context, Prompt or Request Structure. Group 02 What the model produced: Output, Model Execution Metadata, Validation State. Group 03 Where it lives in the business: Operational Identifiers, Workflow Context. Group 04 Whether it can still be trusted: Integrity Reference, Verification State. Group 05 How long it persists: Retention Policy, Lifecycle State. Each group is shown as a labeled section inside a single retained decision record artifact. Bottom callout: Decision evidence preserves enough of the original AI-assisted moment that a reviewer arriving later can inspect it without going back to the workflow itself.](/diagrams/obligra-verify-what-decision-evidence-preserves.svg) * The internal anatomy of decision evidence. Five field families, each answering a question a reviewer arriving later will need to ask. * What the workflow saw is preserved so a reviewer can inspect the input, the retrieved context, and how the model was instructed. What the model produced is preserved as the generated output together with the execution metadata and validation state. Where the decision lives in the business is preserved as operational identifiers and workflow context that reviewers already use to talk about the work. Whether the record can still be trusted is preserved as the integrity reference and verification state. How long the record persists is preserved as retention policy and lifecycle state. The lifecycle state matters as much as the captured content. A retained record moves through recorded, validated, attested, verified, and (when applicable) superseded states. Reviewers read the state before they read the content, because the state determines how much trust can be placed in what comes next. That property is not available in a log line. It is a property of the record itself. ## 06. Why logs fall short as evidence Logs are not designed to be the system of record for an AI-assisted decision, and the ways they fall short are structural rather than incidental. The same properties that make logs useful for operations make them weak as decision evidence. Logs are fragmented across services. The retrieved context lives in one place, the prompt assembly in another, the model response in a third, the validation outcome in a fourth, and the downstream workflow update in a fifth. A reviewer who needs all five pieces to make sense of the decision is asked to do correlation work that the system itself never did. Logs expire under log-retention policy, not under decision-record retention policy. Storage cost, security posture, and operational hygiene all argue for shorter log retention. Decision evidence has the opposite pressure: review windows for AI-assisted decisions are measured in months and years, and the retention posture must be customer-defined, not operator-defined. Logs are difficult to verify as unchanged. The contents of a logging pipeline can be re-emitted, sampled, enriched, or rewritten by intermediate components, and there is rarely a single integrity reference a reviewer can check against. Decision evidence carries that integrity reference as a property of the record. The compounding consequence of these properties is that teams forced to use logs as evidence end up doing reconstruction work on every review. That work is slow and expensive, pulls engineers away from product work, and produces approximations rather than retained artifacts. A reconstructed explanation may help tell the story, but it is not the same artifact as a retrieved decision record. ## 07. Where this matters in production The distinction surfaces differently in different industries, but the shape of the problem is the same. Reviewers arrive with the business identifier their team already uses, and they either retrieve a record or reconstruct one from logs. ### Healthcare When an AI-assisted summary is questioned during a patient encounter review, the logs show that a service ran, an endpoint was called, and a workflow advanced. The reviewer needs more: which encounter the summary belonged to, what patient-provided input was used, what clinical context was retrieved, what was generated, and whether the retained record for that encounter still verifies. Decision evidence preserves the encounter record. The log only confirms that the system was active. ### Banking and financial services When a transaction is disputed, the logs show that a review workflow invoked a model and that the workflow continued. The reviewer needs the retained record tied to the transaction: the account context, the risk signals, the model output, the escalation result, the validation state, and the current verification state. The log confirms the system ran; decision evidence shows what shaped the review and what output was produced. ### Insurance When a claim is appealed, the logs show that a risk assessment completed. The reviewer needs the retained record tied to the claim: policy context, prior claim history, generated risk output, routing recommendation, review flag, retention state, and verification status. Logs confirm activity; decision evidence preserves what actually happened in a form that can be retrieved by the claim identifier the claims team already uses. Across all three, the shared pattern is the same. Customer teams already have logging. What they are missing is the retained decision evidence layer that sits alongside it. ## 08. Verify is not a logging platform The distinction matters for product positioning as much as for review workflow. Verify is intentionally not the category most teams encounter first when they go shopping for “something to record what our AI is doing.” - Verify is not a logging platform. Logs continue to be operated by the customer team in whatever stack they already use. - Verify is not an observability or monitoring tool. Dashboards, alerts, traces, and metrics live with the observability stack the customer already runs. - Verify is not a telemetry pipeline. It does not ingest streams; it captures specific AI-assisted decisions at execution time. - Verify is not a prompt optimization tool, a model evaluation platform, or a generic AI dashboard. Verify is the system of record for AI-assisted decisions. The record layer is what most organizations are missing. A customer already has logs, traces, dashboards, model providers, workflow systems, and an observability stack. The missing piece is not more activity data. The missing piece is the retained decision record that can be retrieved by operational context, inspected alongside its lifecycle state, and verified at review time. That is the layer Verify provides. ## 09. Reference summary Logs are records of system activity emitted by the runtime. They help engineering and operations teams operate, debug, and investigate systems. Decision evidence is the retained record of an AI-assisted decision, captured at execution time as a structured artifact. It preserves input, context, output, workflow metadata, validation state, integrity metadata, and retention metadata so that a reviewer arriving later can inspect the decision without reconstructing it from logs. The two artifacts answer different questions, persist under different retention pressures, and serve different audiences. Obligra Verify provides the decision record layer that turns AI-assisted decisions into retained, reviewable, and verifiable records, retrieved by the operational context the customer team already uses. Events emitted by an event-driven runtime are a third artifact again — useful for runtime choreography and operational monitoring, but not the system of record for the AI-assisted decision. See [From Events to Decision Records](/resources/from-events-to-decision-records) for that contrast. --- --- title: From Events to Decision Records slug: from-events-to-decision-records category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/from-events-to-decision-records canonicalUrl: "https://obligra.ai/resources/from-events-to-decision-records" llmTags: - llm-aligned - canonical-concept - canonical-concept-source - retrieval-tier-2 --- # From Events to Decision Records _AI Decision Records_ _Customer teams adopting event-driven architectures often assume the existing event log is also the right place to record AI-assisted decisions. The two artifacts solve different problems. Events describe runtime activity from the perspective of a service. Decision records describe the state of an AI-assisted decision from the perspective of later review. Conflating them turns later review into a reconstruction job over an event fabric that was never designed to be the system of record. The shift to retained decision records keeps the existing event infrastructure in place and adds the durable artifact that review actually needs._ ## 01. Overview Event-driven systems are excellent at moving work through software. They emit signals when a service runs, a workflow advances, or a downstream system is updated. Those signals support debugging, incident review, and operational monitoring. They are not the same thing as a decision record. An event tells the runtime something happened. A decision record tells the reviewer what was decided. > Events are signals. Decision records are evidence. The rest of this page walks through the structural difference between the two artifacts, the cost customer teams pay when the event log is treated as a system of record, and how a retained decision record fits alongside the existing event fabric rather than replacing it. ## 02. Event vs decision record A system event is a point-in-time signal emitted by the runtime. It is scoped to a service or a request and tuned for debugging, latency analysis, and operational alerting. It usually carries a small number of fields — event type, workflow ID, timestamp, service name, status code, trace ID — chosen for the systems that consume the event downstream. A decision record is a retained artifact preserved when the workflow ran. It is scoped to the AI-assisted decision rather than to one service, and it is tuned for later retrieval, review, and verification. It carries the input, retrieved context, output, execution metadata, operational identifiers, workflow state, integrity reference, and retention metadata associated with the decision. ![Two cards with a versus arrow between them. The left card is a system event, scoped to one service. The right card is a decision record, scoped to one AI-assisted decision. Bottom takeaway: Events are signals. Decision records are evidence.](/diagrams/obligra-verify-event-vs-decision-record.svg) *Events are signals. Decision records are evidence.* | System event | Decision record | | --- | --- | | eventType | Input — the request the workflow handed to the model | | workflowId | Retrieved Context — the supporting material assembled for the call | | timestamp | Output — the AI-assisted result the workflow used | | serviceName | Execution Metadata — model, provider, version, timestamps | | statusCode | Operational Identifiers — case, encounter, transaction, workflow IDs | | traceId | Workflow State — accept, reject, edit, override, escalate | | — | Integrity Reference — used to verify the retained record | | — | Retention Metadata — policy class, retention window, access controls | A model output event may show that a model returned a result. It does not, on its own, preserve the input the workflow handed to the model, the retrieved context assembled for the call, the prompt or request structure, the model metadata, the validation results, the operational identifiers, or the integrity reference the reviewer needs months later. Those fields belong to the decision record, not the event. ## 03. The cost of event-only architectures Event-driven architecture is the right tool for the systems it was designed for: observability, choreography between services, asynchronous workflows, and operational alerting. The problem shows up when the same fabric is asked to answer the question a reviewer arrives with months later: what was decided with AI assistance, with what context, and is the retained record still trustworthy? When the event log is the only artifact, that question becomes a reconstruction job across multiple systems. The input may exist in one place, the model response in another, the workflow state in a third, and the final business outcome in a fourth. Human review actions may live in a separate table or UI layer. Retention periods differ across each system. The reviewer ends up assembling a likely narrative from artifacts that were never designed to be combined into one record. The artifacts that survive each have a different purpose. Application logs are tuned for debugging and rotate on schedules optimized for storage cost. Workflow tables preserve the final state of the process, not the state the AI-assisted step saw. Tickets capture the human-side annotations after the fact. Tracing spans describe latency and span hierarchy, not decision content. None of these are the system of record. The operational cost is recurring. Every audit, every dispute, every regulator inquiry, every legal hold, and every incident reopens the same reconstruction. The cost shows up as longer investigations, slower audits, more engineering time spent on review support, higher dependence on specialist knowledge of the runtime, and weaker answers when scrutiny arrives. ## 04. From workflow event to decision record The transition is not about removing events. It is about adding a retained decision record at the moment the AI-assisted output influences the workflow. The runtime continues to emit events for the systems that need them. The customer integration also submits the decision context to Verify, which preserves it as one structured retained record. ![Four stage cards in a horizontal flow with arrows between them. Stage 01 Workflow Event runs in the customer runtime. Stage 02 Decision Boundary runs in the customer integration. Stage 03 Decision Record runs in the Verify platform and is visually elevated as the hero. Stage 04 Retrieve and Review runs in the customer review program. Bottom takeaway: Events keep the runtime moving. Decision records preserve the AI-assisted moment.](/diagrams/obligra-verify-workflow-event-to-decision-record.svg) *The runtime keeps emitting events. Verify captures the AI-assisted moment as a retained record.* A basic event might look like this: ```json { "eventType": "model.output.generated", "workflowId": "claim_12903", "timestamp": "2026-04-27T14:12:03Z", "serviceName": "claims-ai", "statusCode": 200 } ``` That event is useful for operations. It is not enough for later review. A decision record carries the information needed to retrieve, read, and verify the decision later: ```json { "decisionRecordId": "dec_842193", "workflowId": "claim_12903", "operationalContext": { "claimId": "claim_12903", "policyId": "policy_50092" }, "input": { "claimId": "claim_12903", "lossType": "water_damage" }, "retrievedContext": { "sources": ["policy_doc_50092", "claims_history_12903"] }, "output": { "riskLevel": "moderate", "recommendedAction": "manual_review" }, "execution": { "model": "claims-risk-v3", "provider": "anthropic", "modelVersion": "2026-03-12" }, "validation": { "manualReviewRequired": true }, "verification": { "verificationStatus": "valid" }, "retention": { "retentionPolicy": "governance_7_years" } } ``` The event keeps the runtime observable. The decision record keeps the AI-assisted decision reviewable. ## 05. Anatomy of the retained record The retained record is intentionally one object per AI-assisted decision. It binds the input, retrieved context, output, execution metadata, operational identifiers, workflow state, integrity reference, and retention metadata together so the reviewer reads one artifact rather than reassembling several. ![Anatomy of a Decision Record. A structured visual showing the fields a retained decision record preserves at execution time. The record bundles the input the workflow sent to the model, the retrieved context assembled for the call, the prompt or request structure, the model execution metadata, the output the workflow used, the validation state, the operational identifiers the customer team uses to find the record, the workflow state that followed the AI-assisted step, the integrity reference used to verify the record later, and the retention metadata that controls how long the record is kept and who can access it.](/diagrams/obligra-verify-anatomy-of-a-decision-record.svg) * The anatomy is intentional: one retained object per AI-assisted decision, indexed by operational context, verifiable on read. * The structure does not change as the runtime changes underneath it. The customer team can swap providers, rewrite the orchestration layer, change the workflow engine, or move the integration between cloud and on-prem environments. The retained record shape remains stable, which is why reviewers can compare records across providers and across time without relearning the runtime. ## 06. Where this matters in production The shift from events to retained decision records shows up most clearly in workflows where review, dispute, and regulatory inquiry are part of the operating model. ### Healthcare and telehealth A telehealth workflow may use AI to draft a visit summary, draft a patient-facing reply, or support documentation quality. Event logs show that a model endpoint was called and a workflow step advanced. The retained decision record preserves the encounter identifier, the patient-provided input, the retrieved clinical or operational context, the generated summary, the validation state, the review metadata, and the integrity reference. A later clinical quality review retrieves the record by encounter ID and verifies it before reading. ### Banking and financial services A transaction review workflow may use AI to classify risk, propose a review priority, or draft a response to a customer. Event logs show that the model was invoked and the workflow advanced. The retained decision record preserves the transaction identifier, account context, retrieved risk signals, generated recommendation, validation outcome, escalation status, and verification metadata. The dispute team retrieves the record by transaction ID without learning the runtime. ### Insurance A claims workflow may use AI to assess claim risk, suggest routing, or summarize prior history. Event logs show the model call and the workflow transition. The retained decision record preserves the claim identifier, policy context, prior claim history, generated risk output, routing recommendation, validation results, and retention state. The appeals or legal team retrieves the record by claim ID and verifies it before review. The industries differ. The structural problem is the same: events show activity, and review needs the retained decision record. ## 07. Where Verify fits alongside the event fabric Obligra Verify sits above the existing application, workflow, and event stack. It does not replace the model provider, the workflow engine, the message bus, or the observability tools. Those systems continue to do their jobs. What Verify adds is the retained decision record layer. At the point where an AI-assisted output becomes part of a real workflow, the customer integration submits the decision context to Verify, which preserves it as one structured retained artifact indexed by the operational identifier the customer team already uses. The operating model shifts from **“we can probably reconstruct this later”** to **“we can retrieve the preserved decision directly.”** The event fabric stays in place. The retained decision record removes the reconstruction job that previously fell on the reviewer. ## 08. Reference summary Events describe runtime activity from the perspective of a service. Decision records describe the state of an AI-assisted decision from the perspective of later review. Both have a role; only one is the system of record for the decision. A retained decision record preserves the input, retrieved context, output, execution metadata, operational identifiers, workflow state, integrity reference, and retention metadata associated with the AI-assisted decision. It is one stable artifact per decision, indexed by the operational identifier the customer team already uses. Obligra Verify provides that record layer alongside the existing event fabric. Reviewers stop reconstructing decisions from event sources and start retrieving them directly. Application logs are a third artifact again — they describe service activity rather than runtime choreography or AI-assisted decisions. See [Evidence vs Logs](/resources/evidence-vs-logs) for that contrast. --- --- title: From Sandbox to Production slug: from-sandbox-to-production category: Operations & Governance retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/from-sandbox-to-production canonicalUrl: "https://obligra.ai/resources/from-sandbox-to-production" llmTags: - llm-aligned - canonical-concept - operations-governance - canonical-concept-source - retrieval-tier-2 --- # From Sandbox to Production _Operations & Governance_ _Moving Obligra Verify from a working proof of concept to a governed production deployment is a four-stage maturity arc, not a configuration change. Sandbox proves the integration works on one workflow. Validation extends that proof across every workflow that will produce retained decision records. Pilot puts a limited production rollout behind the Customer-Owned Proxy with the Capture Decision Policy enforced. Production runs the steady state. Each stage has its own operational signal, governance milestone, and exit criterion. Each handoff is the work. This page is the reference for which stage an organization is in, what must be true to leave it, and which team owns what._ ## 01. Overview Teams reach a familiar point in the [Quickstart](/resources/quickstart) and pause: one verified retained decision record exists, the integration code works, and the next question becomes harder than the one it just answered. What does it actually take to get from one verified Sandbox record to a deployment the organization is operating in Production? Read the diagram first ![A five-stage horizontal flow with arrows. Stage 01 Sandbox owned by the Builder team. Stage 02 Validation owned by the Builder team. Stage 03 Pilot owned by the Platform team. Stage 04 Production owned by Operations and Governance. Stage 05 Governed Deployment is the destination steady state, visually elevated. Bottom takeaway: Sandbox proves the integration works. Governed Deployment proves the organization is operating Verify, not just running it.](/diagrams/obligra-verify-sandbox-to-production-maturity.svg) *Five stages, four arrows, one destination. The fifth card is the operating shape the first four stages produce, not a separate piece of work.* Each stage has its own operational signal, governance milestone, and exit criterion. The table below is the at-a-glance reference; the per-stage sections that follow carry the nuance. | Stage | Runs at | Operational signal | Governance milestone | Exit criterion | | --- | --- | --- | --- | --- | | 01 Sandbox | Builder team · Verify Sandbox | Capture, retrieve, verify loop runs end to end on one workflow. | Integration owner identified. | One verified record retrieved by the operational identifier the team will use in Production. | | 02 Validation | Builder team · Customer AI workflow | Capture, retrieve, verify pass for every workflow that will produce retained records. | Review program owner identified per workflow. | Every in-scope workflow has passed the loop with the team’s business identifier. | | 03 Pilot | Customer environment, behind the Customer-Owned Proxy | Working review and verification cadence on retained records. | Retention policy approved by compliance and legal. | A real reviewer outside the implementation team has signed off on one full pilot record cycle. | | 04 Production | Customer environment, full scope | Steady-state retrieval and verification at expected volume. | Annual governance review scheduled and owned. | 90 days of clean operation against capture and retrieval targets. | | 05 Governed Deployment | Steady state · recurring | Review, verification, investigation, audit run as recurring activities. | Each milestone above continues to hold. | Destination state. No exit. | > **Read this page as a self-assessment.** For each stage, the operational signal and the governance milestone are concrete. If both are true, the organization is in that stage. If either is missing, the organization is still in the previous stage, regardless of what the integration code looks like. ## 02. Stage 01 — Sandbox Sandbox is the proof-of-concept stage. A builder team has completed the Quickstart on the Verify Sandbox and has one verified retained decision record retrievable by an operational identifier the team chose. The capture, retrieve, and verify loop has been exercised end to end on a single workflow. ### What “success” means at this stage Success in Sandbox is not the number of records captured. It is whether the loop works once on the workflow the team will extend in Validation. A team that has captured one hundred test records but never retrieved one of them by its business identifier has not finished Sandbox. ### Operational signal that ends Sandbox The capture, retrieve, and verify loop runs end to end on one chosen workflow. A reviewer who was not on the implementation call can retrieve the record by its business identifier without needing the builder team in the room. ### Governance milestone The integration owner is identified by name and by team. Verify is now owned by a specific person, not by “the team that’s evaluating it.” ### Exit criterion One verified record has been retrieved by the operational identifier the team will use in Production. > Sandbox does not introduce new product concepts. The integration shape, the record contents, and the verification mechanic are owned by the canonical pages in Fundamentals, Architecture, and Developers. Sandbox owns only the question “has the integration been proved against one workflow?” ## 03. Stage 02 — Validation Validation extends the Sandbox proof. The builder team now adds capture for every AI-assisted workflow that will produce retained decision records in Production, and validates the capture, retrieve, and verify loop for each one. Validation still runs against the Customer AI workflow, not yet inside the customer’s production environment. ### What changes from Sandbox Sandbox proved the integration works on one workflow. Validation proves it works on all of them. The shape of the operational identifier that retrieves the record is confirmed per workflow, because the workflow that retrieves by a claim identifier and the workflow that retrieves by a transaction identifier are structurally different review surfaces. ### Operational signal that ends Validation Capture, retrieve, and verify pass on every workflow the team has scoped for Production. No workflow is in “we will get to it later.” ### Governance milestone A review program owner is identified for each workflow. Verify will not be operated as a single review program. A team that owns fraud review is not the team that owns claims review, and each owner needs to be named before the Pilot begins. ### Exit criterion Every workflow that will produce retained decision records in Production has passed the capture, retrieve, and verify loop, with the operational identifier matching the business identifier the review team uses today. ## 04. Stage 03 — Pilot Pilot is the first stage that runs inside the customer’s environment. The Customer-Owned Proxy is deployed, the Capture Decision Policy is enforced inside the customer boundary, and the Field Retention Policy is configured. Pilot is limited — one workflow, one region, one customer segment — but it is real traffic against the production architecture. > The architectural change between Validation and Pilot is documented on > [Capture Boundary vs Proxy](/resources/capture-boundary-vs-proxy) and > [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . This page does not re-explain either — it names them as the entry signals for Pilot. ### What changes from Validation Validation proved every workflow can produce a retained record. Pilot proves the organization can review and verify those records in a recurring cadence inside the customer’s environment. The platform owners, security reviewers, and compliance owners who will sign off on Production all see Pilot data first. ### Operational signal that ends Pilot There is a working review and verification cadence on retained records. A reviewer retrieves records on the chosen pilot workflow on a recurring schedule, verifies them, and acts on them. Failed verifications have an escalation path that has been used at least once. ### Governance milestone The Field Retention Policy and the overall retention window have been approved by compliance and legal. The retention conversation does not get to wait for Production. ### Exit criterion A real reviewer who is not on the implementation team has signed off on at least one pilot record cycle: retrieved by business identifier, verified, reviewed, acted on, retained. ## 05. Stage 04 — Production Production is the full-scope rollout. Every workflow validated in Validation is now in scope. Environment- specific API keys separate non-production from Production traffic. Monitoring covers capture success rate and retrieval latency. The on-call rotation knows what a Verify-related incident looks like. The customer-side review workflows that retrieve retained records by the business identifier the team already uses are in place and being used. ### What changes from Pilot Pilot proved the review cadence works on a slice. Production extends that cadence to the full surface area. The difference between Pilot and Production is not technical — it is volume, scope, and the operational maturity to keep the cadence working when it is not the only thing the team is doing. ### Operational signal Steady-state retrieval and verification at expected production volume. Capture success rate and retrieval latency hold to their targets across at least 90 days of continuous operation. ### Governance milestone An annual governance review is scheduled and owned. The owner is not the integration owner from Sandbox. ### From Production to Governed Deployment Production is a stage. Governed Deployment is the operating shape Production produces over time. An organization reaches Governed Deployment when review, verification, investigation, and audit run as recurring operational activities rather than one-time events — when Verify has stopped being a project and started being a system the organization operates. ## 06. Why Sandbox projects stall before Production Many Sandbox projects work. Fewer reach Production. The gap is rarely technical; the integration that produced one verified record can produce one thousand. Projects stall for organizational reasons that compound silently until the team realises the next stage has no path forward. Four failure modes account for most of them. - **No governance owner** — _Failure mode 01_ — The integration is owned by a builder; the governance program is owned by no one. Compliance and legal hear about Verify for the first time at Pilot, when retention policy approval becomes blocking. The project stalls waiting for an owner who was never identified. - **No operational ownership** — _Failure mode 02_ — The builder team finishes the integration and the project is treated as complete. No platform team owns the Customer-Owned Proxy, no operations team owns the runbooks. When Pilot traffic arrives there is no team to operate it, and the integration team is asked to do operational work it was not staffed for. - **No production criteria** — _Failure mode 03_ — Production becomes a date on a slide, not a set of conditions. Without explicit operational signals and governance milestones per stage, the project enters Production by calendar rather than by readiness. The first failed verification then triggers a retroactive Pilot. - **No review workflow** — _Failure mode 04_ — Records are captured. Records are not retrieved. A retained record that no reviewer reads is not a system of record — it is a write-only log with a longer retention window. Projects that do not commit a review program to retrieve records by the team’s business identifier discover at Production that they built the wrong half of the system. > **The pattern across all four:** the integration is treated as the project, and the operating shape is treated as a follow-on. The arc on this page inverts that order. The operational signal and governance milestone for each stage are what move the project forward; the integration code is what makes those signals possible. ## 07. Common stage-transition mistakes Adoptions that stall typically stall at one of a handful of transitions. Organizations discover the same pattern: the team treats the transition as a configuration step and discovers later it was a maturity step. The mistakes below are operational and organizational, not technical. | Transition | Mistake | What it actually needed | | --- | --- | --- | | Sandbox → Validation | Extending capture before retrieval by business identifier has been confirmed on the first workflow. | Finish Sandbox first. The retrieval shape per workflow is not a Validation concern. | | Sandbox → Validation | Skipping the per-workflow review-program owner conversation. | Name an owner per workflow before adding capture for it. | | Validation → Pilot | Promoting to Pilot before the Customer-Owned Proxy is deployed inside the customer environment. | Pilot runs inside the customer boundary. Direct Integration belongs to Validation, not Pilot. | | Validation → Pilot | Treating the Capture Decision Policy as an architectural detail rather than a policy that compliance and legal will need to read. | The policy is governance work disguised as configuration. Compliance reviews the policy text before Pilot, not after. | | Pilot → Production | Promoting to Production before a real reviewer has retrieved and acted on a Pilot record. | The reviewer cadence is what proves Pilot. No cadence, no Production. | | Pilot → Production | Skipping the retention policy approval and assuming legal can review it on a back-channel later. | Retention is the slowest decision in many organizations. Start it in Validation, finish it in Pilot. | | Production → Governed Deployment | Treating Production as the finish line. | Production is a stage. Governed Deployment is the operating shape Production produces over time. The transition is months of steady-state cadence, not a separate project. | ## 08. Production-readiness pillars Each maturity stage is unlocked by a different pillar. Technology unlocks Pilot. Process unlocks Production. Governance unlocks Governed Deployment. ![Three pillar cards in horizontal order with arrows between them. Pillar 01 Technology unlocks Pilot. Pillar 02 Process unlocks Production. Pillar 03 Governance unlocks Governed Deployment, visually elevated as the destination pillar. Bottom takeaway: Skip a pillar and the next stage stalls.](/diagrams/obligra-verify-readiness-pillars-progression.svg) *Skip a pillar and the next stage stalls.* ### Technology pillar — six readiness items Technology readiness is what unlocks Pilot. The conditions below have to be true before the customer environment can run real Verify workloads. | Item | What it means | | --- | --- | | Customer-Owned Proxy | Deployed in the target customer environment. | | Capture Decision Policy | Enforced inside the customer boundary. | | Field Retention Policy | Configured per the customer policy. | | API key placement | Secret storage verified end to end. | | Environment-specific keys | Non-production and Production split. | | HTTPS egress confirmed | From the customer network to Verify. | ### Process pillar — six readiness items Process readiness is what unlocks Production. The conditions below have to be true before the team can operate the integration at production volume. | Item | What it means | | --- | --- | | Operational runbooks | For capture, retrieval, and verification. | | Retrieval by team identifier | Verified against the team’s actual business identifier. | | Capture & retrieval monitoring | Success rate and latency, with alerts. | | On-call rotation | Covers Verify-related incidents. | | Webhook delivery monitored | For downstream review workflows. | | Verification spot-check cadence | Quarterly verification on a sampled record set. | ### Governance pillar — six readiness items Governance readiness is what unlocks Governed Deployment. The conditions below have to be true for the deployment to mature into ongoing operation. | Item | What it means | | --- | --- | | Review program assigned | To retrieve and verify retained records. | | Audit cadence defined | Daily, weekly, monthly, or quarterly. | | Retention policy approved | By compliance and legal owners. | | Escalation path documented | For records that fail verification. | | Investigation runbook | References retained records as evidence. | | Annual governance review | Scheduled and owned. | These conditions are not a one-time launch checklist. They need to remain true during production operations. > The Technology-pillar items are owned by the canonical pages in Architecture ( [Capture Boundary vs Proxy](/resources/capture-boundary-vs-proxy) , > [Environment Strategy](/resources/environment-strategy) , > [API Key Placement](/resources/api-key-placement-and-secret-storage) , > [Network and HTTPS Egress](/resources/network-and-https-egress) ). This page lists them as readiness items, not as architectural definitions. ## 09. Governance milestones tied to each stage Organizations typically discover governance work late, not because it is hard but because it is invisible until a stage transition requires it. The challenge becomes retrofitting governance onto a Pilot that was scoped without it. The operational guidance is to tie one governance milestone to each stage so the work happens in the stage that needs it, not the stage after. | Stage | Governance milestone | Why this stage | | --- | --- | --- | | 01 Sandbox | Integration owner identified by name and by team. | Without a named owner, the integration is everyone’s problem and no one’s. | | 02 Validation | Review program owner identified per workflow. | Review programs do not generalize. The owner per workflow is the one who decides what “review” means there. | | 03 Pilot | Retention policy approved by compliance and legal. | Retention is the slowest governance decision. Starting it at Production is too late. | | 04 Production | Annual governance review scheduled and owned. | Steady-state operation needs a forcing function. The annual review is the calendar invite that prevents drift. | | 05 Governed Deployment | Review, verification, investigation, and audit are recurring operational activities, not events. | The destination state is defined by cadence, not by configuration. | ## 10. Organizational ownership shifts The team that proves the integration is rarely the team that operates it. Adoptions that stall in Pilot most often stall because the builder team is still treated as the operator, with no handoff scheduled. The arc requires two explicit handoffs. ![Three team cards in horizontal order with arrows between them. Team 01 Builder owns Sandbox and Validation. Team 02 Platform owns Pilot. Team 03 Operations and Governance owns Production and Governed Deployment, visually elevated as the steady state. Bottom takeaway: The team that proves the integration is rarely the team that operates it.](/diagrams/obligra-verify-organizational-ownership-shift.svg) *Three teams, two handoffs. The handoff is the work, not a side effect of it.* Each team owns more than a stage. The table below names what each team owns operationally, the cadence they run, and what the next team picks up at handoff. | Team | Owns stages | Owns operationally | Cadence | Hands off to | | --- | --- | --- | --- | --- | | 01 Builder | Sandbox, Validation | Integration code, capture wiring, SDK integration, first verified record. | Weekly progress review. | Platform Team at the end of Validation. | | 02 Platform | Pilot | Customer-Owned Proxy, Capture Policy, environment keys, pilot review program. | Operational rehearsal during Pilot. | Operations & Governance at the end of Pilot. | | 03 Operations & Governance | Production, Governed Deployment | Production runbooks, retention policy, review programs, audit cadence. | Daily monitoring, weekly review, monthly governance review. | Steady state. No further handoff. | ### Why the handoffs matter A handoff is not an email. It is a scheduled session where the outgoing team walks the incoming team through what they own, what they have not finished, and what they have decided to leave alone. Adoptions that skip the handoff invariably re-do work the previous team already completed, because the new team has no record of what was decided. ### What to put in each handoff Each handoff covers four things: the list of items the incoming team now owns, the list of items the incoming team can change, the list of items the incoming team must not change without going back to the outgoing team, and the cadence on which the two teams will meet during the first 30 days post-handoff. ## 11. After this page This page is the entry point to the Operations & Governance category. The pages it leads into describe what the four-stage arc produces — the operational rhythm, the role separation, and the investigation shape of a Governed Deployment. - **[Capture Boundary vs Proxy](/resources/capture-boundary-vs-proxy)** — _Foundations referenced above_ — The architectural decision Pilot makes. Owned by the Architecture canonical, not redefined here. - **[Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy)** — _Foundations referenced above_ — The capture-policy definition that the Pilot enforces inside the customer boundary. Owned by Developers. - **[Environment Strategy](/resources/environment-strategy)** — _Foundations referenced above_ — Sandbox versus Production environment shape. The architectural pillar that unblocks Pilot. - **[Quickstart](/resources/quickstart)** — _Next on the operations arc_ — The page that ends where this one begins: a working Sandbox record. Return here to start the arc. - **[Customer Integration Patterns](/resources/customer-integration-patterns)** — _Next on the operations arc_ — The integration shapes that Validation chooses among. Owned by Architecture. - **[Reference Architecture: AWS](/resources/reference-architecture-aws)** — _Next on the operations arc_ — The production architectural shape Production typically takes inside an AWS-native customer environment. > **What this category does not re-teach.** Operations & Governance does not redefine decision records, verification, operational context, capture boundary, or integration patterns. When those concepts are needed, they are cross-linked to their canonical pages in Fundamentals, Architecture, or Developers. This category teaches how organizations operate Verify after deployment, not how Verify works. --- --- title: A Model-Agnostic Record Layer slug: model-agnostic-record-layer category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/model-agnostic-record-layer canonicalUrl: "https://obligra.ai/resources/model-agnostic-record-layer" llmTags: - llm-aligned - canonical-concept - architecture-core - canonical-concept-source - retrieval-tier-2 --- # A Model-Agnostic Record Layer _AI Decision Records_ _Enterprise AI stacks do not stay fixed. Customer teams change models for cost, latency, accuracy, privacy, and contractual reasons, and individual workflows often span more than one provider over their lifetime. A retained decision record layer survives that evolution only if it is model-agnostic by design. Verify preserves AI-assisted decisions in a stable record format that holds across model changes, provider changes, cloud changes, and the hybrid or on-prem deployments most enterprise customers eventually adopt — so one review program can span a portfolio of AI-assisted workflows that do not look alike at the model layer._ ## 01. Overview Enterprise AI stacks change. Customer teams change models for cost, latency, accuracy, privacy, security, contractual, and availability reasons. Different teams inside the same organization may run different providers. Some workflows run through commercial model APIs. Others run through cloud-hosted platforms, private deployments, internal models, hybrid environments, or on-prem infrastructure. That flexibility is useful, but it creates a record problem. If the retained record of an AI-assisted decision depends on one provider’s history, response format, retention behavior, or platform-specific audit trail, the organization inherits a fragile evidence model that drifts every time the model layer changes underneath it. > The model layer changes. The record layer stays stable. ![One Record Model Across Deployment Environments. A layered visual showing five different inference environments converging on one retained decision record layer. The top row shows five inference paths: a direct model API path, a cloud-hosted AI service path, a multi-cloud routing path, a hybrid deployment path, and a private or on-prem model path. Underneath, a single Verify Decision Record Layer captures the same retained record shape from any of the five paths, with the shape labeled to include input, retrieved context, prompt or request structure, model execution metadata, output, validation state, operational identifiers, workflow state, integrity reference, and retention metadata. Bottom callout: The model layer changes. The record layer stays stable.](/diagrams/obligra-verify-one-record-across-deployments.svg) * Inference paths vary by provider, cloud, and deployment shape. The retained decision record above them remains the same. * The rest of this page walks through why the model layer keeps moving, what goes wrong when the retained record follows the provider, and what the model-agnostic record contract looks like in practice. ## 02. Why the model layer keeps moving Few customer teams stay on one provider forever. The model layer shifts for predictable reasons. ### Provider change The team moves from one provider to another for cost, latency, procurement, security, platform standardization, or quality reasons. The workflow continues to produce AI-assisted decisions; the runtime that produces them changes. ### Multi-model routing The workflow starts using more than one model. One provider handles classification, another handles drafting, a third acts as fallback under degraded service or quota pressure. The router decides at runtime; the retained record needs to absorb that variation without becoming model-path dependent. ### Cross-team expansion One business unit uses one provider, another uses a different one, and both still need to preserve and review decisions in a consistent way. Without a stable record layer, every team ends up with its own record shape. ### Deployment shape change The workflow starts on a commercial model API and later moves to a managed cloud service, a hybrid path, or an on-prem deployment. The inference path changes; the retained record should not have to be redesigned each time. ## 03. What goes wrong when the record follows the provider The provider integration is necessary — the question is whether it is also allowed to define the retained record. When it is, the customer team inherits four predictable problems. ### The retained record changes when the provider changes Request format changes. Response structure changes. Available metadata changes. Parser behavior changes. Even when the business workflow stays the same, the retained record starts to look different from one provider era to the next, and historical records become harder to compare with current ones. ### Multi-model workflows produce uneven records One model path may preserve richer context than another. One provider may expose different execution metadata. One fallback path may save less. The same business workflow produces different record quality depending on which model handled the request. ### Downstream tooling becomes brittle Review interfaces, exports, QA tooling, audit support, and reporting all become harder to maintain when the underlying record shape shifts with the provider. The customer team ends up writing translation logic on top of the inference layer to keep the review layer stable. ### Teams become cautious about changing providers A team may want to switch providers for good reasons, but hesitate because the migration now affects not just inference, but also retrieval, review, reporting, and governance. That is a self-inflicted form of lock-in. ![Two columns. The left column shows four provider stacks each producing their own record shape: Provider A, Provider B, Provider C, and an internal model. The right column shows the same four providers feeding into a single Verify decision record layer that preserves one record shape regardless of provider. Bottom takeaway: Provider-specific records fragment the history. A model-agnostic record layer absorbs the variation underneath.](/diagrams/obligra-verify-provider-vs-model-agnostic.svg) *Every provider migration fragments the evidence base. The model-agnostic record layer absorbs the variation.* ## 04. The model-agnostic contract The model-agnostic contract is straightforward: the model layer produces the output, and the retained record layer preserves the decision. Those are different responsibilities, and the customer team is free to evolve one without disturbing the other. In practice, model-agnostic also means deployment-agnostic. The retained record shape is the same whether the workflow runs through a commercial model API, a managed cloud service, a multi-cloud router, a hybrid environment, or an on-prem model endpoint. The customer team chooses the inference path. The retained record absorbs the variation. Verify does not select, switch, route, or evaluate models. Model orchestration, fallback behavior, and inference governance remain in the customer’s application layer. The retained record is the durable evidence around those decisions, not the inference pathway. Provider-specific fields can still attach to the retained record where they are useful; they do not define the core shape. > The model produces the output. The record layer preserves the decision. ## 05. What customer teams standardize A model-agnostic record layer only stays stable if the customer team makes a few decisions consistently. The conventions below are the ones to set early, so records created today can be retrieved and reviewed the same way months later, even after the model layer changes underneath. ### Stable workflow IDs Choose a stable, human-readable workflow ID per business workflow (for example, `wf-clinical-summary-v1`) and keep it stable across model and provider changes. Workflow ID is the primary handle reviewers use to group records that belong to the same business activity over time. ### Operational context fields Choose the business identifiers that travel with every record — encounter ID, claim ID, transaction ID, case ID, or equivalents from the source system. Reviewers retrieve records by the identifiers they already use in the business workflow, not by timestamps or trace IDs. ### Model metadata fields Capture a fixed minimum set of model metadata — typically provider and model ID, plus version when available. This lets reviewers explain which model produced the output without coupling the record shape to provider-specific fields. ### Environment names Use a small, fixed set of environment names (commonly sandbox, staging, production) and apply them consistently across teams. Reviewers and retention policy both depend on environment to scope what they see and how long records are kept. ### Validation and review states Standardize the validation states the workflow records at capture time (for example, passed, failed, skipped) and the review statuses the workflow records later (for example, pending, approved, rejected, escalated). A consistent vocabulary keeps outcomes comparable across model paths and across teams. ### Retention expectations Decide retention windows per environment and per workflow, aligned to internal policy and regulatory obligations. Retention is a customer responsibility, and reviewers need to know how long a record will be available before they rely on it. ### Reviewer access and escalation Decide which roles inside the customer workspace can read records, search records, and request verification. Document the escalation path a reviewer follows when a record returns *not verified* or *verification unavailable*. Least-privilege access is both a control requirement and a procurement-review expectation. ### Production approval rules Define what must be true before a workflow moves from sandbox to production capture — for example, a sandbox record retrieved and verified end to end, retention configured, reviewer access granted, and the escalation path documented. A clear production gate prevents premature production records that do not match retention or review expectations. ## 06. What this means for risk and compliance For chief risk and chief compliance officers, a model-agnostic record layer is a control requirement rather than an architecture preference. If decision evidence is tied to one model provider, the organization’s review process becomes dependent on that provider’s retention model, metadata structure, access controls, regional availability, and history format. That dependency creates risk every time the model layer changes. A regulator, auditor, legal team, or internal review function does not only need to know which model produced an output. They need to know what decision was made, what context existed, what workflow it belonged to, what controls applied, and whether the retained record still verifies. A consistent record layer gives the organization a consistent evidence structure across model changes, provider changes, cross-team expansion, and migration. The business value is not provider flexibility on its own. It is continuity of decision evidence across the lifetime of the workflow, regardless of how the model layer evolves underneath it. ## 07. Reference summary Model-agnostic means the retained decision record does not depend on any one provider’s response format, metadata conventions, or integration path. It is also deployment-agnostic: the record shape is the same whether the workflow runs through a commercial model API, a cloud-hosted service, a multi-cloud router, a hybrid environment, or a private endpoint. A retained decision record preserves the input, retrieved context, output, execution metadata, operational identifiers, workflow state, integrity reference, and retention metadata associated with the AI-assisted decision. That shape stays stable while the model layer changes underneath. Obligra Verify provides the model-agnostic record layer. AI-assisted decisions become retained, retrievable, and verifiable records that the customer team can review consistently across providers, clouds, deployment shapes, and time. --- --- title: Operational Context Mapping slug: operational-context-mapping category: Architecture retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/operational-context-mapping canonicalUrl: "https://obligra.ai/resources/operational-context-mapping" llmTags: - llm-aligned - architecture-core - retrieval-model - integration - canonical-concept-source - retrieval-tier-2 --- # Operational Context Mapping _Architecture_ _Most retained decision records that prove difficult to retrieve in audit or compliance review trace back to a single capture-time decision: which business identifiers were attached to the record as operational context. Reviewers arrive months later with the identifiers their teams already use day-to-day — claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId, workflowId — not internal record IDs, prompt text, or trace IDs. Choosing operational context deliberately is the single most consequential integration decision the customer team makes, because it determines whether reviewers can find records months later without depending on knowledge of how the workflow was implemented._ ## Overview Most retained decision records that prove difficult to find in audit or compliance review trace back to a single capture-time decision: which business identifiers were attached as operational context. Operational context is the set of stable business identifiers a customer team already uses day-to-day to talk about the work being performed — the claim, the encounter, the transaction, the escalation, the policy, the review case, the support ticket. Attached to a retained decision record at capture time, those identifiers become the keys reviewers will use later to retrieve the record without depending on internal record IDs, prompt text, or knowledge of how the AI-assisted workflow was implemented. In practice, mapping operational context is a customer-side architectural decision that is made once, early, and intentionally. The cost of getting it right at integration time is small; the cost of getting it wrong — or of deferring the decision and accepting whatever identifiers the application code happens to emit — surfaces months later, under audit, compliance, legal, risk, or operational review pressure, when the team that would correct it has long since moved on. > Operational context is the retrieval key — choose it for the reviewer who will arrive months later. > > > > > The right identifiers are the ones your reviewers already use day-to-day. The wrong identifiers are the ones your workflow happened to generate — request IDs, internal trace IDs, temporary tokens. Future retrieval depends entirely on this choice. ## What operational context is Inside a retained decision record, operational context is a small object of stable customer-recognizable identifiers attached at capture time. Verify treats those identifiers as retrieval keys — operators query for records using the same values their teams already use to refer to the underlying work, which is what allows retrieval to feel obvious rather than archaeological months later. The customer team decides which identifiers belong there. In practice, the shortlist is the small set of values reviewers will actually have in hand when they arrive months later — the claim number, the encounter, the transaction, the escalation, the policy, the review case — anchored on what the customer’s authoritative systems already call them. Identifiers are paired with a stable workflowId so retrieval can be scoped both to the kind of work and the specific unit of work. The values must match the customer’s authoritative systems exactly: same casing, same prefixing, same shape. A claimId of `CLM-220145` retrieves the same record reviewers see in the claims system. The shape is the contract; once it drifts, retrieval drifts with it — and the drift is the kind of issue that is easy to ship and expensive to discover. Worth being explicit about the tradeoff: operational context is the retrieval handle, not the payload. Full prompts, model output bodies, PHI, PII, and unrelated business data have other places to live on the record (or stay inside the customer environment under the Field Retention Policy). Operational context names the work; it does not embed it. Teams that conflate the two end up with retrieval keys that are difficult to share, difficult to index against, and difficult to defend in audit. ### Safe example shape ```json { "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214", "reviewCaseId": "REV-4402" } } ``` The exact fields are customer-defined. Verify does not enforce a fixed identifier schema — the customer team picks the identifiers that match how their operational reality is described internally. Stability and reviewer-familiarity are the two qualities that matter. ## Why retrieval depends on operational context Verify is a retrieval-oriented system of record, and the consequence of that framing is concrete: reviewers do not arrive months later with internal record IDs in hand. They arrive with a claim number, an encounter, a transaction, an escalation, or a case reference. Whether those reviewers can find the retained decision record at all depends on whether the right operational context was attached at capture time. In practice, reviewers retrieve with what they know. Customer operations, claims handlers, fraud analysts, compliance reviewers, legal teams, and auditors arrive with the business identifier that prompted the review — not a Verify record ID. The retrieval surface that matters is the one anchored on the identifier the rest of the audit trail already uses; anything else introduces a translation step at exactly the moment reviewers can least afford one. Retrieval is the durable interface, and durability is the tradeoff that pays off slowly. Internal record IDs may not be portable across customer systems; business identifiers persist inside the customer’s authoritative systems of record and stay meaningful across releases. The longer a retained record is held, the more important that stability becomes — and the more expensive it becomes to retrofit later. Reconstruction is not a substitute. Trying to recover the AI-assisted context after the fact by re-running the workflow is not a reliable review surface; the operational reality the workflow saw may already have changed. Operational context decouples review from implementation: reviewers do not need to understand how the AI-assisted workflow was built. They retrieve by what they already know and inspect what was preserved. > If retrieval is hard later, the wrong identifiers were chosen earlier. > > > > > Every retrieval friction point during a review traces back to a capture-time decision about which identifiers became operational context. Get this right once and the retrieval surface stays clean for the lifetime of the integration. ## Choosing stable business identifiers The single most important property of an operational-context identifier is stability. Reviewers should be able to use the same identifier value six, twelve, or thirty-six months later and still retrieve the right retained decision record. In practice, the qualities below are the heuristics most customer teams converge on after their first compliance review — the ones that earn their place by surviving the conditions retrieval actually has to operate under. ### Qualities of a good identifier - **Reviewer-familiar** — Already used by the customer team in their day-to-day operational vocabulary. Reviewers should not need a translation layer to know what a claimId or transactionId is. - **Authoritative-system anchored** — Originates in the customer's authoritative system of record (claims platform, EHR, accounting platform, CRM, policy admin system). The identifier is well-defined outside the AI-assisted workflow. - **Release-stable** — Shape and casing do not change across software releases. Reviewers retrieving an old record should be using the same identifier format the system used at capture time. - **Migration-aware** — Survives downstream system migrations, vendor changes, or data-store consolidations. If the customer team plans to migrate, the operational context should anchor on the identifier the migrated state will still carry forward. - **Operationally meaningful** — Tied to a real business entity reviewers care about — a claim, encounter, transaction, escalation, or case — not to a transient request, span, or trace. - **Non-sensitive** — Reviewers and auditors can use it without exposing sensitive payload content. The identifier names the work; it does not embed the content of the work. ### Qualities to avoid - Random UUIDs generated inside the AI-assisted workflow with no anchor in the customer's authoritative systems. - Request IDs, trace IDs, span IDs, correlation IDs — useful for engineering debugging, not for operational retrieval. - Session tokens, bearer-token fragments, or any value derived from authentication state. - Timestamps, sequence numbers, or counters whose meaning depends on the runtime that produced them. - Opaque keys, system-generated tokens, or other unrecognizable values that reviewers have no way to map back to a real piece of work when they arrive later. - Anything that contains PHI, PII, raw payload content, or sensitive business data — the identifier should name the work, not embed it. ## Identifier examples by domain The right identifiers depend on the operational reality of the customer’s domain. The shapes below are illustrative starting points — customer teams should pair them with the identifiers their authoritative systems already use. ### Healthcare and telehealth - encounterId — clinical encounter, visit, intake session, or post-encounter summary workflow. - patientReference — non-sensitive patient identifier from the customer's authoritative system (a record-system patient reference, not a raw PHI field). - episodeOfCareId — multi-encounter clinical episode where reviewers may want a longitudinal view. - reviewCaseId — quality assurance review, peer review, or post-encounter audit sampling. - workflowId — for example, intake-summary, post-visit-followup, prior-auth-triage. ```json { "workflowId": "post-visit-summary", "operationalContext": { "encounterId": "ENC-771034", "episodeOfCareId": "EPI-2204", "patientReference": "PR-99214" } } ``` ### Insurance - claimId — the claim under review, the primary retrieval key for claims operations. - policyId — the underlying policy or account, useful when reviewers look across the policy lifecycle. - appealId — claim appeals, redetermination workflows, or coverage re-review. - reviewCaseId — claims operations, SIU, fraud review, or compliance sampling. - workflowId — for example, claims-review, fraud-triage, appeals-redetermination, coverage-eligibility-check. ```json { "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214", "reviewCaseId": "REV-4402" } } ``` ### Financial services - transactionId — payment, transfer, settlement, or trade identifier from the customer's authoritative system of record. - accountReference — non-sensitive account identifier from the customer's authoritative system. - disputeId — chargeback, transaction dispute, or merchant-side adjudication workflow. - escalationId — fraud escalation, AML escalation, or risk operations escalation. - workflowId — for example, transaction-review, dispute-triage, fraud-investigation, aml-screening. ```json { "workflowId": "dispute-triage", "operationalContext": { "transactionId": "TXN-99124430", "disputeId": "DSP-77204", "accountReference": "ACC-44021" } } ``` ### Customer operations and support - ticketId — support ticket, complaint case, or service request from the customer's helpdesk system. - escalationId — escalated case under review by senior operations, trust and safety, or compliance. - customerReference — non-sensitive customer identifier from the customer's authoritative CRM. - workflowId — for example, support-triage, complaint-handling, refund-review, escalation-summary. ```json { "workflowId": "complaint-handling", "operationalContext": { "ticketId": "TKT-880214", "escalationId": "ESC-22035", "customerReference": "CUST-44021" } } ``` ### Internal review, audit, and compliance - reviewCaseId — internal review case across any domain, the canonical retrieval key for reviewers. - auditSampleId — audit sampling identifier where a record is one of many drawn into a periodic audit. - controlId — the control or policy being exercised when the record was captured (useful for compliance traceability). - workflowId — for example, audit-sampling, policy-check, periodic-review, quality-assurance. ```json { "workflowId": "audit-sampling", "operationalContext": { "reviewCaseId": "REV-4402", "auditSampleId": "AUDIT-2026-Q1-77", "controlId": "CTRL-ACR-12" } } ``` The same record can carry operational context spanning more than one of these vocabularies — a claim review record may carry both claimId and reviewCaseId, a complaint case may carry both ticketId and escalationId. See the shape and cardinality section below for guidance on multi-identifier records. ## workflowId and operationalContext together workflowId and operationalContext are different concepts and they pair together at capture time. Both should be attached on every retained decision record. - **workflowId** — A stable identifier for the operational workflow that produced the record. Examples: claims-review, fraud-triage, intake-summary, complaint-handling, audit-sampling. Shared across many records produced by the same workflow. - **operationalContext** — The set of stable business identifiers that name the specific work this record corresponds to. Examples: claimId, encounterId, transactionId, escalationId, reviewCaseId, policyId. Unique to the individual unit of work. ### How they work together workflowId scopes retrieval to a category of work — all records produced by claims-review, all records produced by fraud-triage. operationalContext scopes retrieval to a specific unit of work — this claim, this encounter, this transaction. Together they let reviewers retrieve cleanly: *the claims-review record for CLM-220145*, *the fraud-triage record for TXN-99124430*, *the audit-sampling record for REV-4402*. Both values are customer-owned. Neither should be generated inside the AI-assisted workflow, and neither should change across releases, runtime changes, or downstream system migrations. workflowId names the operational workflow; operationalContext names the work that workflow handled this time. ## Shape and cardinality Operational context should be a small, focused object of stable identifiers — not a place to attach everything the workflow happened to know. The customer team is choosing the retrieval contract reviewers will rely on, not collecting metadata for its own sake. Keep operational context minimal. Three to six identifiers is the typical range — the primary retrieval key, one or two related anchors, and any cross-system references reviewers will need. Beyond that, the retrieval surface becomes noisy and the values stop earning their place. Use customer-recognizable field names and values. Prefer `claimId` over `claim_uuid_internal_v2`; prefer the claims system’s exact format for the value over an internal re-encoding. Reviewers should read the field name and the value and instantly know what they are looking at, without a translation layer. A single record can carry more than one retrieval key when reviewers may legitimately retrieve by any of them — for example, claimId + policyId + reviewCaseId. Avoid overlap, though: `claimId` and `claim_id` pointing at the same value is duplication. Pick one canonical field name and use it everywhere. Keep values short — identifiers are retrieval keys, not payload. ### Multi-identifier records Some workflows naturally produce records that reviewers will want to retrieve by any of several business identifiers. Attaching all of them at capture time keeps the retrieval surface flexible without complicating capture. ```json { "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214", "reviewCaseId": "REV-4402", "appealId": "APL-77204" } } ``` Reviewers can later retrieve this record using whichever identifier is most natural to their workflow — claims operations may retrieve by claimId, the appeals team by appealId, the audit team by reviewCaseId. ## What operational context is not Operational context exists for retrieval. It is not a replacement for the customer’s authoritative systems of record, and it is not a dumping ground for everything the workflow happened to know. - Not a duplicate of the customer's authoritative system of record. The claims system, EHR, accounting platform, or CRM remains the source of truth; operational context names the work, it does not duplicate it. - Not a place for full records. Do not attach full claim records, full encounter notes, full transaction details, or full case files. The retained decision record carries its own AI-assisted context; operational context is the retrieval key. - Not a place for prompts. Prompt text belongs in the AI-assisted context fields of the record where applicable — not in the retrieval key. - Not a place for model output bodies. Model output bodies belong in the AI-assisted context fields of the record where applicable — not in the retrieval key. - Not a place for PHI or PII. Raw patient data, raw account data, raw transaction body data, and similar sensitive content do not belong in operational context. The identifier names the work; it does not embed the content. - Not a place for credentials or tokens. API keys, bearer tokens, session identifiers, and any authentication artifact must never appear in operational context. - Not a place for unrelated business data. Operational context is scoped to retrieval keys for this specific record. Customer-side metadata that does not help retrieval belongs elsewhere in the customer's own systems. > Operational context names the work. It does not embed the work. > > > > > If the value of an operational-context field is longer than an identifier reasonably should be, or contains free-form text rather than a stable identifier shape, it does not belong there. ## Stability across releases and migrations Retained decision records may be retrieved months or years after the workflow that produced them. Operational-context identifiers should survive whatever software releases, system migrations, or downstream consolidations happen between capture and review. ### Stability practices Anchor on identifiers issued by the customer’s authoritative system of record. Those identifiers tend to be contractually defined, stable across software releases, and reused by downstream audit programs — exactly the properties retrieval relies on years later. Treat the identifier shape and the field name as a contract. If `claimId` today is `CLM-NNNNNN`, it should still be `CLM-NNNNNN` after the next release; renaming `claimId` to `claim_id` or `claim_reference` partway through the integration breaks retrieval for any prior records. The customer team should keep a short internal note describing which authoritative system each operational-context field comes from and what it represents. When the customer team plans to migrate from one authoritative system to another, capture a stable cross-system reference (for example, both the legacy claimId and the post-migration claimId) during the migration window so retrieval continuity survives the cutover. > Treat operational-context field names as a contract with future reviewers. > > > > > A retrieval-by-claimId workflow that the operations team relies on today should still work the same way after a release that has nothing to do with the AI-assisted workflow. Stability is the property that makes that possible. ## Anti-patterns The pitfalls below are the most common operational-context mapping mistakes customer teams encounter. Reviewing them before Sandbox rollout reduces friction during Production rollout and reduces review-confusion risk later. | Anti-pattern | Why it matters | Better pattern | | --- | --- | --- | | Using request IDs or trace IDs as operational context | Request and trace IDs are engineering debugging artifacts. Reviewers will not have them months later; retrieval by trace ID is not an operational workflow. | Use the business identifier reviewers already know — claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId. | | Using random UUIDs with no business meaning | A UUID generated inside the AI-assisted workflow has no anchor in the customer's authoritative systems. Reviewers cannot retrieve by a value they have no way of knowing. | Anchor on identifiers issued by the customer's authoritative system of record. UUIDs are fine as additional metadata, not as the retrieval key. | | Using temporary or placeholder values in Production | Values like CLM-TEST-1, FAKE-123, or debug strings make later retrieval painful and contaminate the operational retrieval surface. | Use only real business identifiers in Production. Sandbox can carry test identifiers — Production records should reflect operational reality. | | Mixing identifiers from different environments | A record captured in Production should carry Production identifiers. Mixing Sandbox-shaped or test-shaped identifiers into Production creates a retrieval surface reviewers cannot trust. | Confirm the identifier values match the active environment. Treat environment-context drift as a capture-time validation failure. | | Changing identifier formats across releases | Records captured under the old format will not retrieve under the new format. Future reviewers must maintain a translation table to find old records — a long-lived audit liability. | Treat the operational-context identifier shape as a contract. If the shape must change, document the migration explicitly and capture both shapes for the migration window. | | Dumping full payloads into operational context | Records become harder to inspect, retrieval surfaces become noisy, and sensitive payload content may end up in places it does not belong. | Operational context is the retrieval key, not the payload. Attach identifiers; keep AI-assisted context and workflow evidence in their own fields where applicable. | | Renaming operational-context fields without notice | Field renames break retrieval-by-field-name for any prior records. Reviewers who relied on the old name lose retrieval continuity. | Treat operational-context field names as a contract. Add new fields when the operational vocabulary genuinely grows; do not silently rename existing ones. | | Embedding PHI, PII, or raw payload data in identifiers | The identifier should name the work, not embed the content of the work. Embedding sensitive content in retrieval keys expands the surface where that content can appear. | Use non-sensitive customer-side references — record-system patient references, account references — that name the work without embedding sensitive payload. | | Omitting operational context altogether | Records cannot be retrieved later using information reviewers already know. The retrieval surface becomes unreliable, and future reviewers fall back to brittle workarounds. | Always attach workflowId and at least one stable business identifier at capture time. Retrieval is the durable interface. | ## Validation checklist Before promoting an integration from Sandbox to Production, the following operational-context-mapping controls should all be in place. - Every retained decision record carries a stable workflowId — and the workflowId value matches the customer team's operational vocabulary. - Every retained decision record carries at least one stable business identifier in operationalContext — claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId, or equivalent. - The identifiers used in operationalContext are issued by the customer's authoritative system of record — not generated inside the AI-assisted workflow. - Identifier shapes match the customer's authoritative systems — same prefixing, same casing, same length conventions. - Operational-context field names are stable across releases — no silent renames, no shape changes without an explicit migration plan. - Sandbox records and Production records use shape-consistent identifiers — no test-only formats leaking into Production records. - Sandbox retrieval has been validated end-to-end — a record captured under representative operational context can be retrieved using the same identifier reviewers will use in Production. - Operational context does not contain payloads, prompts, model output bodies, PHI, PII, credentials, or unrelated business data. - Customer teams reviewing records (operations, compliance, fraud, audit, legal) recognize the field names and values without needing a translation layer. - The customer-side mapping (which authoritative system each operational-context field comes from) is documented for the next team member who onboards a workflow. ## Related documentation Pair this guide with the following resources for the full retrieval-oriented picture: - [Install and Configure Verify — canonical first-time developer onboarding loop including operational-context capture end-to-end.](/resources/install-and-configure-verify) - [Server-Side Capture Pattern — trusted server-side capture topology including operational-context attachment.](/resources/server-side-capture-pattern) - [Environment Strategy — Sandbox vs Production separation including environment-aware retrieval scope.](/resources/environment-strategy) - [API Key Placement and Secret Storage — credential placement discipline for the capture path that attaches operational context.](/resources/api-key-placement-and-secret-storage) - [Retrieval by Operational Context — foundational concept of retrieval-by-operational-context across the Verify model.](/resources/retrieval-by-operational-context) - [Retrieval Model — how decision records are located, returned, and inspected in Verify.](/resources/retrieval-model) - [Structure of a Decision Record — the customer-visible record shape including workflowId and operationalContext.](/resources/structure-of-a-decision-record) - [Verify API Reference — first-time-user API reference including retrieval by operational context.](/resources/api-reference) - [Verify SDK Reference — capture SDK methods including operational-context attachment.](/resources/verify-sdk-reference) --- --- title: Retrieval by Operational Context slug: retrieval-by-operational-context category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/retrieval-by-operational-context canonicalUrl: "https://obligra.ai/resources/retrieval-by-operational-context" llmTags: - llm-aligned - canonical-concept - retrieval-model - canonical-concept-source - retrieval-tier-2 --- # Retrieval by Operational Context _Architecture_ _Reviewers do not retrieve AI-assisted decisions the way engineers debug systems. An auditor opening a dispute, a compliance officer reviewing a case, a clinician revisiting an encounter, or a fraud analyst pulling a transaction all arrive with the same kind of identifier: the business identifier their team already uses. The category differentiator behind Verify is that retrieval is anchored on those identifiers, not on prompts, request IDs, trace IDs, or log entries. This page walks the reviewer’s search behavior, the two retrieval paths that result, and why operational context is the only retrieval handle that survives platform and infrastructure changes._ ## 01. Overview A reviewer opening a dispute does not know the request ID. A compliance officer reviewing a case does not have the trace ID. A clinician revisiting an encounter does not search by prompt. A fraud analyst pulling a transaction does not query by log entry. Every one of them arrives with the same kind of handle: the business identifier their team already uses to talk about the work. The category differentiator behind Verify is that retrieval is anchored on those identifiers. Decision records are not retrieved by timestamp, by prompt, or by platform-internal trace. They are retrieved by the operational context the workflow was already in. > Reviewers search by business context, not model interactions. For the foundational thesis behind preserving the record in the first place, see [Why Retrieval Beats Reconstruction](/resources/why-retrieval-beats-reconstruction) . The question this page picks up is what happens next: once the record exists, what is the right handle to retrieve it by, and why? ## 02. How reviewers actually search Two kinds of handles could theoretically be used to retrieve a retained decision record. Only one of them matches how reviewers actually think about their work. ![How Reviewers Actually Search. A three-zone visual that contrasts the two retrieval handles a reviewer might use. Left column, TECHNICAL ARTIFACTS: Prompt, Request ID, Trace ID, Log Entry, each shown as a small chip; these are the platform-internal handles reviewers cannot reason about. Right column, OPERATIONAL CONTEXT: Case ID, Claim ID, Transaction ID, Encounter ID, Workflow ID, each shown as a larger labeled card; these are the business identifiers reviewers already use to talk about their work. Center: Decision Record Retrieval, a hero card showing the retained record as the single retrieval destination both columns funnel into. Mapping arrows show that retrieval by operational context is the path actually used in production, while retrieval by technical artifact is the path that requires investigation. Bottom callout: Reviewers search by business context, not model interactions.](/diagrams/obligra-verify-how-reviewers-actually-search.svg) * Two possible retrieval handles. The right column is the vocabulary every audit, compliance, operations, risk, and legal team already uses; the left column requires engineering knowledge most reviewers do not and should not need. * Technical artifacts live inside the platform. Prompts, request IDs, trace IDs, and log entries are valuable to engineering teams operating the AI-assisted workflow, but they are not the vocabulary the surrounding business uses. An auditor cannot find a prompt by reading a ticket; a compliance officer does not file a case by request ID. Asking the rest of the business to learn the platform’s vocabulary in order to retrieve a record is asking the wrong team to do the translation work. Operational context is the opposite. Case IDs, claim IDs, transaction IDs, encounter IDs, and workflow IDs are already the handles every downstream system uses to talk about the same work. Anchoring retrieval on those handles means the reviewer arrives where they were already going. The translation work happens once, at capture time, when the customer team attaches the operational identifier the workflow was in; from then on, retrieval matches the reviewer’s mental model rather than the platform’s internals. ## 03. Retrieval without operational context When the retained record cannot be retrieved by the business identifier the reviewer already has, retrieval becomes investigation. The reviewer arrives with a question, the customer team gathers whatever artifacts can be found, and the answer is assembled by hand. The assembly cost is paid on every question. ![Retrieval Without Operational Context. A vertical flow showing the painful retrieval path when records cannot be retrieved by the business identifiers reviewers already use. Stage 01 a question is raised about an AI-assisted decision. Stage 02 Fragmented Sources, the reviewer gathers evidence from four scattered artifacts in parallel: Logs, Tickets, Emails, Screenshots. None of these were built around the business identifier the reviewer arrived with. Stage 03 Manual Correlation, the reviewer assembles the four artifacts by hand into something that approximates the original decision. Stage 04 Review, the review proceeds against a reconstructed approximation. Callout: Retrieval becomes investigation.](/diagrams/obligra-verify-retrieval-without-operational-context.svg) * Without an operational-context retrieval handle, retrieval reduces to four parallel investigations none of the source systems were designed to support. * Each of the four artifacts is useful for its original purpose and structurally weak as a retrieval handle for the business question being asked. Logs are indexed by service and timestamp, not by claim. Tickets are filed by symptom, not by case identifier. Emails are narrative, not searchable by encounter. Screenshots are snapshots of UI, not retrieval handles for the underlying record. The reviewer is asked to do the correlation work that none of those sources were built to do. The compounding consequence is that retrieval-by-anything- but-operational-context does not scale. It works once, for a single question, with engineering involved. It does not scale to audit sampling, dispute volume, regulator inquiries, or recurring compliance review, because the assembly cost has to be paid again every time. ## 04. Retrieval by operational context When the retained record carries the operational identifier alongside its captured content, retrieval changes shape. The reviewer arrives with the same identifier their team already uses, the identifier resolves directly to the retained record, and the reviewer inspects, verifies, and reviews on the same artifact. ![Retrieval by Operational Context. A horizontal flow showing the retrieval path when records are retrieved by the business identifier the reviewer already uses. Stage 01 Business Identifier: the reviewer arrives with the case, claim, transaction, encounter, or workflow identifier their team already uses. Stage 02 Decision Record: the identifier resolves directly to the preserved decision record captured at execution time. Stage 03 three actions happen on the same retained artifact: Inspect the captured content, Verify the integrity property, and proceed to Review. Callout: Retrieval begins where the reviewer already is.](/diagrams/obligra-verify-retrieval-by-operational-context.svg) * With an operational-context retrieval handle, retrieval begins where the reviewer already is. No correlation across systems, no assembly cost. * The shape of the work changes. There is no cross-system correlation step. There is no manual investigation phase. The reviewer does not learn the platform’s internal vocabulary, and the engineering team does not become a translation layer between the reviewer’s question and the retained record. Retrieval resolves in one step against the identifier the reviewer arrived with. The retained record itself carries the captured content, the workflow metadata, the validation state, the lifecycle state, and the integrity reference needed for the next steps in the review. For the customer-side surface and the day-to-day operations reviewers perform on retained records, see [Working with Decision Records in Verify](/resources/working-with-decision-records) . ## 05. Operational context across systems A single AI-assisted decision is reviewed by more than one team. Audit asks one set of questions, risk asks another, legal a third, operations a fourth, compliance a fifth. The retained record is the same artifact in every case; what changes is the team and the question. Operational context is what lets the same record be retrieved by each team on terms that match their own work. ![Operational Context Across Systems. A radial visual that shows the retained decision record as a single artifact accessible to five different customer teams who each retrieve by the same business identifier their workflow already uses. The customer workflow produces an AI-assisted decision that is captured as a retained Decision Record. Five customer teams then retrieve the same retained record using the same business identifier: Audit, Risk, Legal, Operations, and Compliance. The retained record carries the operational identifier alongside the captured content, so each team retrieves on terms that match their own work without depending on platform internals, model identifiers, or trace IDs. Bottom callout: Operational context survives platform and infrastructure changes.](/diagrams/obligra-verify-operational-context-across-systems.svg) * One retained artifact, five reviewer surfaces. The operational identifier is the durable retrieval handle that keeps the artifact reachable from each. * The durability of operational context matters as much as its accessibility. Cloud providers change. Observability stacks change. Model providers, prompt templates, and request-handling architectures all change. The business identifier attached to the retained record does not, because it was the identifier the customer’s own systems were already using when the workflow ran. A retrieval handle built on the customer’s own operational identifier continues to work after platform and infrastructure changes that would invalidate any platform-internal handle. ## 06. Operational context primitives The retained record carries a small set of operational context fields that are stable across industries. Each field is the kind of identifier a customer team already uses to navigate its own systems; together they give reviewers more than one way to find the same record without ever leaving the operational vocabulary. | Field | What it identifies | Example identifiers | | --- | --- | --- | | Workflow ID | The customer-side workflow the AI-assisted decision belonged to. | claims-intake, fraud-triage, encounter-summarization, dispute-handling | | Case ID | The case, matter, or review unit the decision is attached to. | audit-case-2026-004812, legal-matter-9981, review-case-A-117 | | Claim ID | The claim (insurance, healthcare, financial) the decision supports. | claim-2026-77103, claim-A-2026-0091, claim-EOB-44820 | | Transaction ID | The transaction the decision is associated with. | txn-2026-1119-44103, txn-card-77a91, txn-wire-2026-0017 | | Encounter ID | The healthcare or telehealth encounter the decision is part of. | enc-2026-04-09-22871, enc-tele-2026-3-9087, enc-A-22-661 | | Reviewer references | Customer-side reviewer or assignee identifiers, per the customer’s access program. | reviewer-A-77, assignee-team-claims-east-2 | The primitives are intentionally generic. The customer team decides which ones apply to its workflow and which identifier shapes to use; the retained record is built to carry the customer’s own vocabulary. For the mapping between a customer workflow and the right primitives, see [Operational Context Mapping](/resources/operational-context-mapping) . ## 07. Where this matters in production The category differentiator surfaces differently in different industries, but the operational pattern is the same. Reviewers arrive with the business identifier their team already uses, retrieval resolves in one step, and the same retained artifact serves audit, risk, legal, operations, and compliance review on terms each of those teams already speaks. ### Healthcare and telehealth A clinician revisiting an AI-assisted encounter summary retrieves by encounterId or episodeOfCareId. A clinical review or audit team revisiting the same decision retrieves by the same encounterId from a different surface. The retained record carries the encounter identifier alongside the captured content; reviewers retrieve in the vocabulary the EHR already speaks. ### Financial services A dispute reviewer arrives with a transactionId or disputeId. A fraud analyst arrives with a transactionId or escalationId. A compliance officer arrives with a caseId or reviewCaseId. The retained record resolves for each on the identifier their team uses, without the downstream review ever needing to learn the platform’s internal vocabulary. ### Insurance A claims reviewer arrives with a claimId. An appeals investigator arrives with a claimId or appealId. An SIU team arrives with a claimId or matterId. The retained record carries the claim identifier alongside the captured content and the lifecycle state; retrieval matches the vocabulary the claims platform was already using. In every case, the retrieval handle that survives is the customer’s own. The handle the platform attaches to the record (request ID, trace ID, prompt) is unnecessary for the review surface and unstable across platform changes; the handle the customer attaches is the one that remains useful for years. ## 08. What retrieval does not claim The retrieval surface is bounded on purpose. Naming the boundary explicitly is what keeps the customer governance posture clear. Retrieval does not adjudicate whether the original AI-assisted output was correct. Correctness is a judgment question owned by the customer review program. Retrieval does not validate the quality of the underlying business identifier; the customer’s own systems remain the authoritative system of record for the case, the claim, the transaction, the encounter, and the workflow. Retrieval does not perform regulatory interpretation. The regulatory standing of any specific decision is owned by the customer compliance program. What retrieval does claim is that the retained record carrying a given operational identifier is reachable in one step, on terms the reviewer already uses, and that the record itself is the surface review proceeds from. The integrity question that follows retrieval — whether the retained record still matches what was captured — is answered by the verification property of the record. For the integrity mechanism itself, see [Record Integrity & Verification](/resources/record-integrity-and-verification) . ## 09. Reference summary Retrieval by operational context is the category differentiator behind Verify. The customer attaches the business identifier the workflow was already in to the retained record at the moment the decision is made; reviewers arriving later resolve the same identifier to the retained record in one step. The alternative — retrieval by prompt, request ID, trace ID, or log entry — is not how reviewers think about their work and is not the vocabulary the surrounding audit, compliance, operations, risk, and legal teams already use. Retrieval handles built on platform internals also do not survive the changes that inevitably happen below them: cloud providers change, model providers change, observability stacks change, but the customer-side identifier does not. Obligra Verify provides the retained record layer that makes this retrieval surface possible. The customer team continues to own the policies, controls, regulatory interpretation, model governance, and review outcomes that surround it. --- --- title: Retrieval Model slug: retrieval-model category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/retrieval-model canonicalUrl: "https://obligra.ai/resources/retrieval-model" llmTags: - llm-aligned - canonical-concept - retrieval-model - canonical-concept-source - retrieval-tier-2 --- # Retrieval Model _Architecture_ _An AI-assisted decision becomes reviewable only when the customer review program can reach it. The retrieval model is the architectural commitment that determines whether they can. Verify is built around one specific commitment: review begins with the business context the customer team is already in, not with the platform-internal artifacts the AI workflow happened to produce. The sections below walk through why that commitment matters, what the retrieval path looks like as a result, and why the alternative — reconstruction from logs, tickets, screenshots, and dashboards — does not scale to real review programs._ ## 01. Overview A retained decision record only becomes useful when someone can reach it. The retrieval model is the architectural commitment behind that reach — the shape of the handle that resolves a question back to the record that answers it. Two retrieval models are possible, and they are not equivalent. One anchors retrieval on platform-internal artifacts: the prompt that was sent, the request ID the API call returned, the trace ID emitted by the runtime, the log entry that resulted. The other anchors retrieval on operational context: the case, claim, transaction, encounter, or workflow identifier the customer team was already using when the AI-assisted decision ran. Verify is built around the second. > Review begins with business context, not with the platform-internal artifacts the AI workflow happened to produce. ![How Reviewers Actually Search. A three-zone visual that contrasts the two retrieval handles a reviewer might use. Left column, TECHNICAL ARTIFACTS: Prompt, Request ID, Trace ID, Log Entry, each shown as a small chip; these are the platform-internal handles reviewers cannot reason about. Right column, OPERATIONAL CONTEXT: Case ID, Claim ID, Transaction ID, Encounter ID, Workflow ID, each shown as a larger labeled card; these are the business identifiers reviewers already use to talk about their work. Center: Decision Record Retrieval, a hero card showing the retained record as the single retrieval destination both columns funnel into. Mapping arrows show that retrieval by operational context is the path actually used in production, while retrieval by technical artifact is the path that requires investigation. Bottom callout: Reviewers search by business context, not model interactions.](/diagrams/obligra-verify-how-reviewers-actually-search.svg) * Two retrieval handles. Only one is the vocabulary every audit, compliance, operations, risk, and legal team already uses; the other requires engineering knowledge most reviewers should not need. * The retrieval model is upstream of the mechanic. The mechanic — how a customer team chooses the right operational identifiers for their workflow, how retrieval resolves across systems, what the retained record looks like once retrieved — lives on the dedicated pages it is reachable from. The retrieval model is the architectural commitment that makes those mechanics worth implementing in the first place. ## 02. Review begins with business context The reviewer arriving at an AI-assisted decision is not a platform engineer. They are an auditor, a compliance officer, a risk analyst, a clinician, a claims adjuster, a fraud investigator, a legal reviewer. None of them comes to the review with a prompt, a request ID, or a trace ID. They come with the business identifier their team has been using all along to talk about the same work. The retrieval model is what lets the reviewer arrive where they already are. The operational identifier the customer attached to the workflow at capture time is the same identifier the reviewer reads from a ticket, looks up in a claims platform, finds in an EHR, or sees on a transaction. Retrieval resolves that identifier to the retained record in one step. The translation work happens once, at capture time, when the customer team chooses which operational identifier the workflow was in; from then on, the platform speaks the customer’s vocabulary, not the other way around. The commitment is durable. Cloud providers change. Observability stacks change. Model providers, prompt templates, and request-handling architectures change. The business identifier the customer attached at capture time does not, because it was the identifier the customer’s own systems were already using. Retrieval handles built on platform internals do not survive those changes; retrieval handles built on operational context do. ## 03. The retrieval path The shape of the retrieval path follows from the commitment. The reviewer arrives with a business identifier; the identifier resolves to the retained decision record; the reviewer inspects, verifies, and reviews on the same retained artifact. There is no correlation across systems, no manual investigation step, and no engineering translation layer between the reviewer’s question and the retained record. ![Retrieval by Operational Context. A horizontal flow showing the retrieval path when records are retrieved by the business identifier the reviewer already uses. Stage 01 Business Identifier: the reviewer arrives with the case, claim, transaction, encounter, or workflow identifier their team already uses. Stage 02 Decision Record: the identifier resolves directly to the preserved decision record captured at execution time. Stage 03 three actions happen on the same retained artifact: Inspect the captured content, Verify the integrity property, and proceed to Review. Callout: Retrieval begins where the reviewer already is.](/diagrams/obligra-verify-retrieval-by-operational-context.svg) * The retrieval path. Business identifier resolves to the retained record in one step; inspection, verification, and review all happen on the same artifact. * The three actions on the retained artifact are intentional. Inspect lets the reviewer read the captured content alongside the lifecycle state. Verify confirms the retained record still matches what was captured at the original AI-assisted moment. Review is the surface where the reviewer’s judgment is recorded. The retrieval model puts all three on the same artifact so the reviewer never has to leave the record they retrieved. For the mechanic by which the reviewer’s business identifier resolves to the retained record — including the operational-context primitives the customer team picks from at capture time — see [Retrieval by Operational Context](/resources/retrieval-by-operational-context) . For the customer-side surface and day-to-day reviewer operations on retained records, see [Working with Decision Records in Verify](/resources/working-with-decision-records) . ## 04. Why reconstruction fails The alternative to a retrieval model is a reconstruction model: rebuild the AI-assisted decision after the fact from whatever artifacts survived. Logs, tickets, screenshots, dashboards, model provider history, workflow state at the moment of review. The reconstruction model is not a hypothetical — it is what most AI-assisted workflows fall back on when no retained decision record exists. Reconstruction fails for three structural reasons. First, the source artifacts were never built around the business identifier the reviewer arrived with: logs are indexed by service and timestamp, tickets by symptom, emails by participant, screenshots by capture time. Translating a business identifier into a useful query across those sources is work the system was not designed to support. Second, the AI-assisted conditions that produced the original output may no longer exist: the prompt template may have moved on, the model may have been swapped, the retrieved context may return different results, and the workflow may only retain its final state. Even when reconstruction produces a similar output, similar is not the same as the original. Third, the assembly cost is paid every time: reconstruction works once, for one question, with engineering involved; it does not scale to audit sampling, dispute volume, regulator inquiries, or recurring compliance review. For the foundational thesis behind preserving the AI-assisted decision as a retained record in the first place — rather than rebuilding it after the fact — see [Why Retrieval Beats Reconstruction](/resources/why-retrieval-beats-reconstruction) . ## 05. Where this matters in production The retrieval model surfaces differently in different industries, but the operational pattern is the same. Reviewers arrive with the business identifier their team already uses, retrieval resolves in one step, and the same retained artifact serves audit, risk, legal, operations, and compliance review on terms each of those teams already speaks. ### Healthcare and telehealth A clinician revisiting an AI-assisted encounter summary retrieves by encounterId. A clinical reviewer or audit team revisiting the same decision retrieves by the same encounterId from a different surface. The retained record carries the encounter identifier alongside the captured content; reviewers retrieve in the vocabulary the EHR already speaks. ### Financial services A dispute reviewer arrives with a transactionId or disputeId. A fraud analyst arrives with a transactionId or escalationId. A compliance officer arrives with a caseId or reviewCaseId. The retained record resolves for each on the identifier their team uses, without the downstream review ever needing to learn the platform’s internal vocabulary. ### Insurance A claims reviewer arrives with a claimId. An appeals investigator arrives with a claimId or appealId. An SIU team arrives with a claimId or matterId. The retained record carries the claim identifier alongside the captured content; retrieval matches the vocabulary the claims platform was already using. ## 06. What retrieval does not claim The retrieval model is bounded on purpose. Naming the boundary explicitly is what keeps the customer governance posture clear. Retrieval does not adjudicate whether the original AI-assisted output was correct. Correctness is a judgment question owned by the customer review program. Retrieval does not validate the underlying business identifier; the customer’s own systems remain the authoritative source of truth for the case, the claim, the transaction, the encounter, and the workflow. Retrieval does not perform regulatory interpretation; the regulatory standing of any specific decision is owned by the customer compliance program. What the retrieval model does claim is that the retained record carrying a given operational identifier is reachable in one step, on terms the reviewer already uses, and that the same artifact supports inspection, verification, and review. The integrity question that follows retrieval — whether the retained record still matches what was captured — is answered by the verification property of the record. For the integrity mechanism, see [Record Integrity & Verification](/resources/record-integrity-and-verification) . For the lifecycle properties review programs operate on, see [Verification Lifecycle](/resources/verification-lifecycle) . ## 07. Reference summary The retrieval model is the architectural commitment that review begins with the business context the customer team is already in. Reviewers arrive with the operational identifier their team uses to talk about the work; retrieval resolves that identifier to the retained decision record in one step; inspection, verification, and review all happen on the same retained artifact. The alternative — reconstruction from logs, tickets, screenshots, and dashboards — is what AI-assisted workflows fall back on when no retained record exists. Reconstruction works once, for one question, with engineering involved. It does not scale to audit sampling, dispute volume, regulator inquiries, or recurring compliance review. The retrieval model is what keeps review out of that path. Obligra Verify provides the retained record layer that makes this retrieval model possible. The customer team continues to own the policies, controls, regulatory interpretation, model governance, and review outcomes that surround it. --- --- title: Structure of a Decision Record slug: structure-of-a-decision-record category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/structure-of-a-decision-record canonicalUrl: "https://obligra.ai/resources/structure-of-a-decision-record" llmTags: - llm-aligned - canonical-concept - canonical-concept-source - retrieval-tier-2 --- # Structure of a Decision Record _Decision Records_ _A reviewer arriving at a retained decision record months after capture has one expectation: the record contains what they need to evaluate the AI-assisted decision without leaving the surface. The structure Verify uses is shaped around that expectation. Eleven field families, captured once at execution time, organized so reviewers can read the families that answer their questions without learning the families that do not. This page is the field-by-field reference for that structure — what each family holds, why it is there, and which review question it answers._ ## 01. Overview A retained decision record is the artifact reviewers inspect after an AI-assisted workflow has moved on. The structure of that record determines whether the review can begin from evidence or has to fall back on investigation. Verify uses one specific structure: eleven field families, captured at execution time, organized so each family answers a question reviewers actually ask. > One record. Eleven field families. Each family is a contract with the reviewer who will read it later. ![Anatomy of a Decision Record. A vertical tree visual showing the 11 field families that make up a Verify decision record. At the top, the record envelope: decisionId, tenantId, schemaVersion, recordType, createdAt, recordStatus. Below the envelope, ten nested field families: input (what entered the workflow), context (retrieved data that shaped the decision), prompt (template, version, instructions, prompt hash), modelExecution (provider, model, version, parameters, runtime), output (raw and structured generated artifact), validation (input and output validation, policy checks), metadata (operational context: workflowId, caseId, service, environment), index (retrieval handles for search), verification (integrity reference, retainedAt, verification status), retention (retention policy, mode, until, legal hold). The visual emphasizes that the record is one structured artifact with all eleven families captured at execution time. Bottom callout: One record. Eleven field families. Captured once when the workflow runs, retrieved later by the business identifier reviewers already use.](/diagrams/obligra-verify-anatomy-of-a-decision-record.svg) * The schema shape of a decision record. Eleven field families, the envelope at the top and ten nested families that carry the captured content of the AI-assisted decision. * ## 02. The record as a contract A decision record is not a free-form log. It is a contract between the team that runs the AI-assisted workflow and the teams that will review the resulting decisions later. The contract is what lets the audit team, the compliance officer, the risk analyst, the clinician, the claims adjuster, and the legal reviewer all read the same artifact and find the field they arrived to read. Three properties of the structure follow from treating it as a contract rather than a schema. First, the structure is stable across model changes: the same fields exist whether the workflow used one provider last quarter and another this quarter, whether the prompt template was v2 or v3, whether the retrieval mode was direct or RAG. Second, the structure is stable across deployment environments: cloud, hybrid, and on-prem deployments produce records with the same shape. Third, the structure is stable across workflows: a single review program can span a portfolio of AI-assisted workflows without per-workflow custom evidence handling. For the broader thesis behind treating the record layer as model-agnostic infrastructure, see [A Model-Agnostic Record Layer](/resources/model-agnostic-record-layer) . ## 03. Field families: a reference The eleven field families fall into three groups by purpose: identity (the envelope), decision content (the eight families that carry the captured decision), and trust and lifecycle (verification and retention). Each family is named and scoped below. ### Identity | Field family | Purpose | Key fields | | --- | --- | --- | | recordEnvelope | Establishes record identity, tenant, schema version, record type, and lifecycle state. | decisionId, tenantId, schemaVersion, recordType, createdAt, recordStatus | ### Decision content | Field family | Purpose | Key fields | | --- | --- | --- | | input | Captures what the workflow received at the AI-assisted moment. | requestType, userInput, structuredFields | | context | Captures the retrieved data that shaped the decision (RAG results, prior history, references). | retrievalMode, sources[], rank, contentSummary, contentHash | | prompt | Captures how the model was instructed: template, version, system instruction, prompt hash, variables. | templateId, templateVersion, systemInstruction, assembledPromptHash, promptVariables | | modelExecution | Captures provider, model, version, runtime parameters, region, and execution telemetry. | provider, modelId, modelVersion, region, parameters, requestId, latencyMs | | output | Captures the generated artifact as produced (raw and structured). | outputType, rawOutput, structuredOutput, confidence | | validation | Captures the policy checks, input validation, output validation, and control results applied to the record. | inputValidation, outputValidation, policyChecks[] | | metadata | Connects the record to the customer’s operational context: workflow, case, service, environment. | workflowId, caseId, service, environment, deploymentVersion, region, createdBy | | index | Optimizes retrieval. Carries the handles reviewers actually search on. | decisionId, workflowId, decisionType, createdAt, verificationStatus, retentionUntil, recordLocation | ### Trust and lifecycle | Field family | Purpose | Key fields | | --- | --- | --- | | verification | Carries the integrity reference and the on-demand verification result. Lets the reviewer confirm the retained record still matches what was captured. | integrityReference, retainedAt, verificationStatus | | retention | Carries the retention policy, retention mode, retention horizon, and legal-hold state for the record. | retentionPolicy, retentionMode, retentionUntil, legalHold | The eleven families are stable. Customer-side decisions about which fields within a family to populate vary by workflow, by industry, and by retention posture, but the family shape itself is the contract reviewers and tooling rely on. ## 04. Which fields answer which review questions The structure is shaped around the questions reviewers actually ask. Reviewers do not read the record front to back; they read the family that answers the question they arrived to ask. ![Which Fields Answer Which Review Questions. A mapping visual that shows the six most common reviewer questions on the left and the field families on the right that answer each one. Question 01 What did the workflow see, answered by Input plus Context. Question 02 How was the model instructed, answered by Prompt. Question 03 What did the model produce, answered by Output plus Model Execution. Question 04 Were the controls applied, answered by Validation. Question 05 Where does this decision live in the business, answered by Operational Metadata plus Index. Question 06 Can the record be trusted, answered by Verification plus Retention. Bottom callout: Reviewers do not read the record front to back. They read the field families that answer the questions their work is built around.](/diagrams/obligra-verify-which-fields-answer-which-review-questions.svg) * The mapping is what makes the structure feel navigable in practice. Reviewers go directly to the family that answers their question. * For the customer-side surface and the day-to-day operations reviewers perform on retained records, see [Working with Decision Records in Verify](/resources/working-with-decision-records) . For the retrieval mechanic itself, see [Retrieval by Operational Context](/resources/retrieval-by-operational-context) . ## 05. Verification, integrity, and retention The verification and retention families are intentionally separate from the decision-content families. They describe what is true of the record itself rather than what is true of the decision the record captures. The verification family carries the integrity reference committed against the retained content at capture time and the most recent verification result. Reviewers read this family to confirm the retained record still matches what was captured at the AI-assisted moment. The retention family carries the retention policy, the retention mode (governance, business, or legal hold), the retention horizon, and any active legal-hold flag. Together, they determine whether the reviewer is reading a trustworthy artifact and how long that artifact is guaranteed to be available. The two families are read in coordination with the lifecycle state on the record envelope. For the full trust-progression model and what each state means operationally, see [Verification Lifecycle](/resources/verification-lifecycle) . For the integrity mechanism itself, see [Record Integrity & Verification](/resources/record-integrity-and-verification) . ## 06. Example: a full decision record The example below shows all eleven field families in a single retained record. The scenario is an insurance claim risk assessment; the same structure applies in healthcare, banking, and any other AI-assisted workflow that captures decisions for later review. ```json { "recordEnvelope": { "decisionId": "dec_842193", "tenantId": "tenant_insureco", "schemaVersion": "1.0", "recordType": "ai_assisted_decision", "createdAt": "2026-04-27T14:12:03Z", "recordStatus": "created" }, "input": { "requestType": "claim_risk_assessment", "userInput": "Customer submitted a claim for water damage in basement.", "structuredFields": { "claimId": "claim_12903", "policyId": "policy_50092", "claimAmount": 12400, "lossType": "water_damage" } }, "context": { "retrievalMode": "rag", "sources": [ { "sourceId": "policy_doc_50092", "sourceType": "policy_document", "title": "Residential Water Damage Coverage", "retrievedAt": "2026-04-27T14:11:58Z", "rank": 1, "contentSummary": "Policy covers sudden water damage subject to exclusions.", "contentHash": "sha256:8f14e45fceea167a5a36dedd4bea2543" }, { "sourceId": "claims_history_12903", "sourceType": "claims_history", "retrievedAt": "2026-04-27T14:11:59Z", "rank": 2, "contentSummary": "Customer submitted 3 water-related claims in prior 12 months.", "contentHash": "sha256:2c26b46b68ffc68ff99b453c1d304134" } ] }, "prompt": { "templateId": "claim_risk_assessment_v3", "templateVersion": "3.4.0", "systemInstruction": "Evaluate claim risk using provided policy and claim history. Return structured JSON only.", "assembledPromptHash": "sha256:9c56cc51b374c3ba189210d5b6d4bf57", "promptVariables": { "claimId": "claim_12903", "lossType": "water_damage", "reviewMode": "initial_review" } }, "modelExecution": { "provider": "model-provider-x", "modelId": "provider-x-large", "modelVersion": "2026-03-15", "region": "us-east-1", "parameters": { "temperature": 0.2, "topP": 0.9, "maxOutputTokens": 600 }, "requestId": "req_model_913842", "latencyMs": 1320 }, "output": { "outputType": "risk_assessment", "rawOutput": "{ \"riskLevel\": \"moderate\", \"recommendedAction\": \"manual_review\" }", "structuredOutput": { "riskLevel": "moderate", "recommendedAction": "manual_review", "reason": "Claim appears covered but frequency pattern requires review." }, "confidence": 0.72 }, "validation": { "inputValidation": { "status": "passed", "checks": ["required_fields_present", "allowed_claim_type"] }, "outputValidation": { "status": "passed", "checks": ["json_schema_valid", "required_fields_present"] }, "policyChecks": [ { "policyId": "manual_review_for_moderate_or_high_risk", "status": "triggered", "result": "manual_review_required" } ] }, "metadata": { "workflowId": "claim_12903", "caseId": "case_77281", "service": "claims-intake-service", "environment": "production", "deploymentVersion": "2026.04.27.3", "region": "us-east-1", "createdBy": "system" }, "index": { "decisionId": "dec_842193", "workflowId": "claim_12903", "decisionType": "risk_assessment", "createdAt": "2026-04-27T14:12:03Z", "verificationStatus": "valid", "retentionUntil": "2033-04-27T00:00:00Z", "recordLocation": "s3://verify-records/tenant_insureco/claim_12903/dec_842193.json" }, "verification": { "integrityReference": "ref_77821", "retainedAt": "2026-04-27T14:12:05Z", "verificationStatus": "valid" }, "retention": { "retentionPolicy": "governance_7_years", "retentionMode": "governance", "retentionUntil": "2033-04-27T00:00:00Z", "legalHold": false } } ``` A reviewer arriving with the claim identifier `claim_12903` retrieves this record in one step (via the metadata or index families), reads the verification family to confirm integrity, reads the output and validation families to evaluate what the workflow produced and which controls applied, and reads the input, context, and prompt families if they need to go deeper into the decision basis. The structure makes that progression possible without leaving the record. ## 07. Model-agnostic by design The eleven field families do not change when the model changes. `modelExecution.provider` may identify a different provider, `modelId` may identify a different model, `modelVersion` may move forward. The shape of the record around those fields does not. This is intentional. Organizations change models more often than they change review programs. A record layer whose schema followed the model would force every downstream review to track those changes; a record layer whose schema is the contract reviewers rely on does not. For the broader thesis, see [A Model-Agnostic Record Layer](/resources/model-agnostic-record-layer) . ## 08. Where this matters in production The eleven-family structure is what lets a single review program span workflows in different industries without re-learning the schema for each. ### Healthcare and telehealth An AI-assisted encounter summary captures the encounter input, the retrieved clinical context, the prompt, the model execution metadata, the generated summary, the validation outcome, and the operational metadata tying the record to `encounterId` and `episodeOfCareId`. A clinician revisiting the summary reads the same eleven families a compliance or audit team would later. ### Financial services A transaction risk assessment captures the transaction input, the retrieved account and risk context, the prompt and model execution metadata, the assessed risk output, the policy checks that escalated the transaction, and the operational metadata tying the record to `transactionId` and `caseId`. Dispute review, fraud review, and compliance review all read the same eleven families. ### Insurance A claim risk assessment (the same scenario as the example above) captures the claim input, the retrieved policy and prior-claims context, the prompt and model execution metadata, the generated risk output, the validation outcome that triggered manual review, and the operational metadata tying the record to `claimId`. The claims team, the SIU team, an appeals investigator, and an internal sampling audit all read the same eleven families. ## 09. What this page does not claim The structure is bounded on purpose. Naming the boundary explicitly is what keeps the customer governance posture clear. The structure does not claim that an AI-assisted output was correct. Correctness is a judgment question owned by the customer review program. The structure does not define the customer’s submission contract; the customer team decides which fields within a family to populate and which identifier shapes to use. The structure does not perform regulatory interpretation; the regulatory standing of any specific decision is owned by the customer compliance program. The structure does not adjudicate model appropriateness; model governance is owned by the customer AI program. What the structure does claim is that the eleven field families are the contract reviewers can rely on, that the structure is stable across model and deployment changes, and that reviewers can find the family that answers their question without learning the families that do not. ## 10. Reference summary A Verify decision record is a structured artifact made up of eleven field families: an envelope (identity), and ten nested families — input, context, prompt, modelExecution, output, validation, metadata, index, verification, and retention. The structure is captured at execution time, retrieved later by the business identifier the reviewer already uses, and read by the field family that answers the reviewer’s question. The structure is intentionally stable across model changes, deployment environments, and workflows. It is a contract with the customer review program, not a schema definition for the platform. Obligra Verify provides the retained record layer that carries this structure. The customer team continues to own the policies, controls, regulatory interpretation, model governance, and review outcomes that surround it. --- --- title: Verification Lifecycle slug: verification-lifecycle category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/verification-lifecycle canonicalUrl: "https://obligra.ai/resources/verification-lifecycle" llmTags: - llm-aligned - canonical-concept - verification - canonical-concept-source - retrieval-tier-2 --- # Verification Lifecycle _Lifecycle_ _Trust in a retained decision record does not arrive all at once. It is built one property at a time, across five stages that the lifecycle makes individually checkable. Captured establishes that the record exists. Validated confirms the record shape is correct. Attested makes the integrity question answerable later. Verified confirms the retained record still matches what was captured. Reviewed records that the surrounding customer review program has acted on the record. Each stage adds a property reviewers can read independently, which is what lets review begin from evidence rather than investigation._ ## 01. Overview A reviewer arriving to revisit an AI-assisted decision does not start with the content of the decision. They start with the trust question: can I act on what this record says? The answer depends on what has happened to the record between the moment it was captured and the moment the reviewer arrived. The verification lifecycle is how that trust question gets answered. Five stages, in order, each adding one checkable property. By the time the reviewer reads the content, the trust answer is already on the record. > Trust does not arrive all at once. It is built one property at a time. ![How Trust Is Established Over Time. A horizontal flagship visual showing how a retained decision record accumulates trust properties across five stages, with a trust meter at the bottom that fills progressively from left to right. Stage 01 Captured: the AI-assisted decision is preserved as a retained record at the moment the workflow runs; trust property gained: the record exists; reviewer question answered: was this decision recorded at all. Stage 02 Validated: the record is evaluated against the customer submission contract; trust property gained: the record shape is correct; reviewer question answered: was the record structurally sound when it entered the system. Stage 03 Attested: an integrity reference is committed against the retained content; trust property gained: integrity is now answerable; reviewer question answered: can this record be verified later. Stage 04 Verified: an on-demand integrity check confirms the retained record still matches what was captured; trust property gained: the artifact under review is the artifact that was captured; reviewer question answered: can the reviewer proceed without first investigating whether the record has been altered. Stage 05 Reviewed: a reviewer has inspected the record and either acted on it or escalated; trust property gained: the record has been seen by the surrounding customer review program; reviewer question answered: has anyone looked at this. Bottom callout: Trust does not arrive all at once. It is built one property at a time, and the lifecycle is what makes each property checkable.](/diagrams/obligra-verify-how-trust-is-established-over-time.svg) * The five stages of the verification lifecycle. Each stage answers one reviewer question and adds one trust property. The lifecycle is what makes each property checkable independently. * The rest of this page walks the five stages in turn — what each one is responsible for, why reviewers care about it specifically, and what the customer review program reads on the record once the stage has run. ## 02. Why trust is cumulative A retained decision record could, in principle, attempt to assert its trustworthiness in one step. The lifecycle deliberately does not work that way. Trust is built up across five separable properties, each of which the reviewer can read independently and each of which can fail independently. The shape matters because review programs do not all ask the same question. An audit team starting an evidence sample wants to know first whether the record exists at all. A compliance officer in a dispute review wants to know whether the artifact under review is the same artifact that was captured. A clinician revisiting an encounter note wants to know whether a human has previously looked at the AI-assisted output. Each of those teams reads a different property; the lifecycle gives each of them a property to read that is theirs. The cumulative shape is also what keeps the customer governance posture clear. Verify does not assert that an AI-assisted decision was the right outcome. The lifecycle assembles the trust properties that the customer review program operates on; the program itself decides what to do with them. For the foundational thesis behind preserving decisions as retained records rather than rebuilding them after the fact, see [Why Retrieval Beats Reconstruction](/resources/why-retrieval-beats-reconstruction) . ## 03. Stage 01: Captured ### The trust property Captured establishes that the record exists. Before anything else, the reviewer needs to know that the AI-assisted decision was preserved as a retained record at all, rather than discarded back into a log line. The property is binary — the record is in the system or it is not — and it is the foundation everything else stands on. ### What happens The customer’s server submits the structured record payload (input, retrieved context, prompt or request structure, model execution metadata, output, validation state, operational identifiers, and any non-sensitive metadata the customer chose to retain) at the moment the AI-assisted workflow runs. Capture happens server-side, inside the Customer-Owned Capture Boundary, before any data is transmitted to Verify. The capture decision and the field retention decision both run inside customer infrastructure. ### Why reviewers care Without a captured record, the rest of the lifecycle has nothing to operate on. A review that opens against an AI-assisted decision and finds no captured record is the same review that has to fall back on reconstruction — logs, tickets, screenshots, dashboards. The Captured property is what keeps the review out of that fallback path. ## 04. Stage 02: Validated ### The trust property Validated confirms the record shape is correct. The record carries the required fields, the identifier shapes the customer declared, and the type discipline the customer’s submission contract specifies. The reviewer who reads this property does not yet know anything about the content of the decision; they only know that the record entered the system intact. ### What happens Validation evaluates the submitted record against the customer submission contract. It runs against the shape of the record, not its content: required fields, identifier presence, type discipline, and consistency with the customer’s declared schema. Records that conform are accepted; records that do not are surfaced back to the customer with a structured error so the submitting workflow can correct course. ### Why reviewers care A record that passes validation is one the customer review program can rely on without additional structural checking. The reviewer does not have to verify that the identifier shapes are right, that the required fields are present, or that the type discipline holds. Those questions were answered at execution time, by code, and the reviewer reads the Validated property to know they were answered. ## 05. Stage 03: Attested ### The trust property Attested makes the integrity question answerable later. An integrity reference is committed against the retained content at the moment the record entered the system. The reviewer who reads this property does not yet know whether the record still matches what was captured; they know only that the question is one the lifecycle can answer when asked. ### What happens Once the record is accepted, an integrity reference is committed against the retained content. The reference is bound to the retained content at the moment the record entered the system. This is what makes the Verified stage answerable later: without an attested integrity reference, the on-demand integrity check has nothing to check against. ### Why reviewers care The Attested property is the difference between a retained record and a verifiable retained record. A record without an integrity reference may still be useful for review, but the reviewer would be reading the captured content on trust. The Attested property is what lets the reviewer postpone the trust decision until the Verified stage is run. ## 06. Stage 04: Verified ### The trust property Verified confirms the retained record still matches what was captured. The on-demand integrity check evaluates the integrity reference committed during Attested against the retained content under review. A clean verification result is what lets the reviewer proceed without first investigating whether the artifact has been altered since capture. ### What happens Verification is run on demand at review time. The integrity reference resolves against the retained content, and the result is recorded as the record’s verification state. The check is idempotent and inexpensive enough to run on every review pass; reviewers commonly read the verification state before reading the content of the record. ![What Verification Confirms, and What It Does Not. A two-column visual that names the integrity question verification answers and the four other questions it does not. Left column, What Verification Confirms: the retained record still matches what was captured at the original AI-assisted moment, the integrity reference resolves cleanly against the retained content, the lifecycle state is consistent with the verification result, and the reviewer can proceed without first investigating whether the artifact has been altered. Right column, What Verification Does Not Confirm: that the original AI-assisted output was the correct outcome (a correctness question, owned by the customer review program), that the input data was complete or accurate (an input quality question, owned by the upstream workflow), that the model was the appropriate model to use (a model governance question, owned by the customer AI program), or that the decision met any specific regulatory standard (a compliance interpretation question, owned by the customer compliance program). Bottom callout: Verification answers one specific question well. Other review questions remain customer-owned and are answered by the surrounding governance program.](/diagrams/obligra-verify-what-verification-confirms.svg) * Verification is scoped. It answers one question well and leaves four other review questions to the customer governance program. * ### Why reviewers care Verified is the trust property reviewers cite when they need to act. A compliance officer responding to a regulator inquiry, an auditor closing a sample, a fraud analyst escalating a transaction, or a clinician revisiting an encounter note all want to know that the retained record under review is the artifact that was captured. The Verified property is what answers that. For the integrity mechanism itself, see [Record Integrity & Verification](/resources/record-integrity-and-verification) . ## 07. Stage 05: Reviewed ### The trust property Reviewed records that the surrounding customer review program has inspected the record and either acted on it or escalated. This is the trust property that connects the retained record to the customer’s own governance program. The reviewer who reads this property knows whether anyone has looked at this record before and what they did. ### What happens A reviewer arriving at the record retrieves it by the business identifier their team already uses, inspects the captured content alongside the lifecycle state and the prior verification result, and records their review activity on the record. For the customer-side surface and the day-to-day operations reviewers perform, see [Working with Decision Records in Verify](/resources/working-with-decision-records) . For the retrieval mechanic, see [Retrieval by Operational Context](/resources/retrieval-by-operational-context) . ### Why reviewers care The Reviewed property is repeatable. A single record may be reviewed many times across its lifetime — once during initial workflow processing, again during an audit sample, again during a dispute, again during a regulator inquiry. Each pass adds to the review history on the record. The next reviewer arriving reads that history before opening the content, which is what keeps one team’s work visible to every team that follows. ## 08. Lifecycle states observable to reviewers Each of the five stages surfaces as a state the reviewer can read on the record. The table below names the states, what each one means operationally, and the review signal the reviewer reads when the state is present. | Lifecycle state | What it means | Review signal | | --- | --- | --- | | Recorded | Stage 01 Captured ran: the record was preserved at execution time and accepted by the retained record layer. | The record exists. The rest of the trust properties are checked separately. | | Validated | Stage 02 Validated ran: the record conformed to the customer submission contract at the moment of capture. | The record shape was correct when it entered the system. | | Attested | Stage 03 Attested ran: an integrity reference was committed against the retained content. | The integrity question is now answerable for this record. | | Verified | Stage 04 Verified has been run and the retained record still matches what was captured. | The reviewer can proceed without investigating whether the artifact has been altered. | | Reviewed | Stage 05 Reviewed ran at least once: a reviewer has inspected the record and either acted on it or escalated. | Someone has already looked at this. The review history names who and when. | | Superseded | A later record has taken the place of this one in the customer’s operational context (for example, after a workflow correction). | Review should typically follow the superseding record; the prior record is preserved for traceability. | | Revoked / Blocked / Replaced | The customer has explicitly removed, suppressed, or substituted the record under their retention or governance policy. | Review surface and access posture depend on the customer’s governance program. | ## 09. Validation, verification, and correctness are different questions Three review questions surface together and are easy to conflate. The lifecycle answers two of them directly and intentionally leaves the third to the customer governance program. ![Validation, Verification, and Correctness are different questions. A three-column visual that distinguishes three review questions that are easy to conflate but answer different things. Column 01 Validation asks whether the captured record conformed to the customer submission contract at the moment of capture; it runs at execution time during stage 02 of the lifecycle; it is owned by Verify and the customer submission contract. Column 02 Verification asks whether the retained record still matches what was captured at the original moment; it runs at review time on demand during stage 06 of the lifecycle; it is owned by Verify against the integrity reference. Column 03 Correctness asks whether the original AI-assisted output was the right outcome for the situation; it runs at review time inside the customer review program; it is owned by the customer governance program, not by Verify. Bottom callout: Verify answers the first two questions on the same retained artifact. The third question is owned by the customer.](/diagrams/obligra-verify-validation-verification-correctness.svg) * Three review questions. The lifecycle resolves two of them as properties of the retained record. The third stays with the customer review program. * Validation is the structural question evaluated at capture time. Verification is the integrity question evaluated at review time. Correctness is the judgment question evaluated inside the customer review program: was the original AI-assisted output the right outcome for the situation? Keeping the three distinct keeps the customer governance posture clear. Verify answers two of them on the same retained artifact; the third is human work, shaped by the customer’s domain expertise, policy interpretation, and review process. ## 10. Where this matters in production The lifecycle shows up in different review programs across industries, but the operational pattern is the same. Reviewers read the trust properties first, content second, and verification on demand. ### Healthcare and telehealth A clinician arriving to revisit an AI-assisted encounter summary reads Validated and Attested first, then runs Verified on demand. By the time they open the content, they know the record was structurally sound when captured, the integrity question was set up correctly, and the artifact under review is the artifact that was captured during the encounter. ### Financial services A dispute or fraud reviewer arrives with a transaction identifier and reads the lifecycle state in order: Recorded, Validated, Attested, Verified, Reviewed. The Reviewed state often tells the reviewer that the transaction has been seen before, by whom, and what was done — before the new review begins. ### Insurance A claims reviewer or appeals investigator arrives with a claim identifier and reads the cumulative trust properties on the claim’s retained record. The record may have moved through Reviewed multiple times across the life of the claim; the lifecycle preserves that review history so the new reviewer arrives with context the previous reviewers built. ## 11. Reference summary The verification lifecycle is the five-stage shape a retained decision record moves through. Captured establishes that the record exists. Validated confirms the record shape is correct. Attested makes the integrity question answerable later. Verified confirms the retained record still matches what was captured. Reviewed records that the surrounding customer review program has inspected the record and either acted on it or escalated. Each stage adds one trust property. The properties accumulate, which is what lets review begin from evidence rather than investigation, and what keeps the customer governance posture intact — Verify answers the structural and integrity questions on the record itself; correctness, input quality, model appropriateness, and regulatory standing remain owned by the customer governance program. Obligra Verify supplies the retained record layer that makes this lifecycle observable to reviewers. The customer team continues to own the policies, controls, regulatory interpretation, and review outcomes the lifecycle supports. --- --- title: Why AI Decisions Need a System of Record slug: why-ai-decisions-need-system-of-record category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/why-ai-decisions-need-system-of-record canonicalUrl: "https://obligra.ai/resources/why-ai-decisions-need-system-of-record" llmTags: - llm-aligned - canonical-concept - system-of-record - canonical-concept-source - retrieval-tier-2 --- # Why AI Decisions Need a System of Record _AI Decision Records_ _Once an AI-assisted output influences a real workflow, it stops being a transient model response and becomes part of an operational decision. Logs, traces, workflow tables, and downstream business records were not designed to preserve those decisions. Reviewers who arrive later — compliance, audit, legal, risk, operations — are then asked to reconstruct what happened from artifacts that were never the system of record. A retained decision record removes the reconstruction step: the structured evidence is preserved at execution time, retrieved by the operational identifier the customer team already uses, and verified before review begins._ ## 01. Overview AI-assisted workflows produce outputs continuously. Most systems can already generate summaries, classifications, recommendations, routing decisions, and workflow suggestions using large language models or other AI services. The harder problem begins after those outputs are used. Once an AI-generated result influences a real workflow, it becomes part of an operational decision. It may shape a clinical note, a customer interaction, a transaction review, a triage path, a fraud classification, or an internal recommendation that affects what happens next. At that point, the organization may later need to retrieve, inspect, explain, and verify what happened. > Generation produces an output. A system of record preserves the decision. ![Two cards with a versus arrow between them. The left card is generation: an output returned by a model and then forgotten by the runtime. The right card is a system of record: a retained decision record preserved at execution time. Bottom takeaway: Generation produces an output. A system of record preserves the decision.](/diagrams/obligra-verify-generation-vs-record.svg) *Generation produces an output. A system of record preserves the decision.* | What generation leaves behind | What a system of record preserves | | --- | --- | | Request logs | Input — the request the workflow handed to the model | | Trace IDs | Retrieved Context — the supporting material assembled for the call | | Workflow status updates | Output — the AI-assisted result the workflow used | | Final downstream business record | Execution Metadata — model, provider, version, timestamps | | Ticket notes | Operational Identifiers — case, encounter, transaction, workflow IDs | | Screenshots | Validation State — review, accept, reject, escalate | | — | Integrity Metadata — the reference used to verify the retained record | | — | Retention Metadata — policy class, retention window, access controls | The rest of this page walks through where existing systems stop, what a system of record has to preserve, how retrieval works once it exists, and why verification is the property that turns a preserved record into a reviewable one. ## 02. Where logs and observability stop Most organizations assume that application logs, tracing, observability tooling, and database history will be enough to answer later questions about an AI-assisted workflow. In practice, that assumption breaks down quickly. Logs are designed to describe system activity. They show that a service was invoked, a model endpoint was called, or a workflow step advanced. They are tuned for debugging, latency analysis, error rates, and short-window incident response. They rotate on schedules optimized for storage cost, fragment across services, and change shape as the application changes. Workflow tables and downstream business records usually preserve the final state of the process: the saved note, the finalized claim, the closed ticket. They do not preserve what the AI-assisted step saw, what it produced before review, or what context shaped the output. ![Logs vs Decision Evidence. A side-by-side visual that contrasts the two artifacts. Left column shows Logs as system-activity records emitted by the runtime, with example fields including timestamp, service name, request ID, trace ID, status code, latency, error message, and retry behavior. Right column shows Decision Evidence as a preserved decision artifact with field families including Input, Retrieved Context, Prompt or Request Structure, Model Execution Metadata, Output, Validation State, Operational Identifiers, Integrity Metadata, and Retention Metadata. Bottom callout: Logs describe activity. Decision evidence preserves the state of a decision.](/diagrams/obligra-verify-logs-vs-decision-evidence.svg) * An organization with comprehensive logging still cannot answer the review questions an AI-assisted workflow generates. The artifacts solve different problems. * The result is a familiar condition: the system contains evidence of activity, but not an authoritative record of the decision. When the question is “did the system run,” logs are sufficient. When the question is “what was decided, with what context, and does the retained record still verify,” they are not. ## 03. What a system of record preserves A system of record for AI-assisted decisions has to preserve more than the model response. It has to capture the decision in a form that supports later inspection, retrieval, and verification — one structured artifact per AI-assisted moment, with the surrounding context bound into it. | Field family | What it preserves | Why later review needs it | | --- | --- | --- | | Input and output | The request or prompt the workflow handed to the model, the response that came back, and the final output the workflow used. | Defines what was actually generated and what was actually acted on. | | Retrieved context | The supporting material assembled at the AI-assisted moment — retrieved documents, structured lookups, policy text, customer context. | Lets a reviewer evaluate the decision under the conditions that produced it. | | Execution metadata | Model, provider, version where available, timestamps, source service, and the workflow step that produced the call. | Ties the retained record to a concrete execution and inference path. | | Operational identifiers | The business identifiers the customer team already uses — case, encounter, transaction, claim, workflow, ticket. | Makes retrieval practical from the business workflow rather than from trace IDs. | | Workflow state | Human review state, validation results, accept or reject decision, downstream actions triggered. | Shows how the output participated in the workflow that followed. | | Retention metadata | Policy class, retention window, storage boundary, and access controls applied to the record. | Determines whether the record remains operationally reliable when reviewers arrive. | | Integrity reference | The reference used to verify that the retained record still matches what was captured. | Closes the integrity loop before the reviewer accepts the record as evidence. | The shape of the artifact matters as much as its content. A decision record is not a denormalized log. It is one retained object that ties the input, context, output, execution metadata, operational identifiers, workflow state, retention controls, and integrity reference together so the reviewer can read it without first rebuilding it. ![Anatomy of a Decision Record. A structured visual showing the fields a retained decision record preserves at execution time. The record bundles together the input the workflow sent to the model, the retrieved context assembled for the call, the prompt or request structure, the model execution metadata, the output the workflow used, the validation state, the operational identifiers the customer team uses to find the record, the workflow state that followed the AI-assisted step, the integrity reference used to verify the record later, and the retention metadata that controls how long the record is kept and who can access it.](/diagrams/obligra-verify-anatomy-of-a-decision-record.svg) * The anatomy is one retained object per AI-assisted decision. The reviewer reads the artifact rather than reassembling it from system fragments. * ## 04. Retrieval by operational context Months after an AI-assisted decision occurs, reviewers rarely remember the exact wording of the prompt or the output. They remember the business context: case number, patient encounter, transaction reference, workflow run, clinician, support ticket, claim, or approximate time window. Retrieval has to be built around that context, not around payload search alone. The reviewer arrives with the identifier their team already uses, and the identifier resolves directly to the retained decision record. The reviewer does not learn the runtime to find the artifact. ![Operational Context Across Systems. A horizontal visual showing the operational identifiers a customer team already uses across healthcare, financial services, and insurance workflows, including case ID, encounter ID, transaction ID, claim ID, workflow ID, and ticket ID. The identifiers route into the Verify decision record layer, which resolves them to the retained decision record without requiring the reviewer to know which trace ID, log range, or database table the runtime used.](/diagrams/obligra-verify-operational-context-across-systems.svg) * The reviewer’s starting point is the business identifier. Retrieval resolves it directly to the retained record, regardless of the runtime path the workflow took. * ## 05. Verification turns storage into evidence Preserving a record is not enough on its own. A reviewer arriving later needs a way to confirm that the record they retrieve is the record that was originally captured. Verification is that property. Without verification, the reviewer is asked to trust that the retained record still matches the original capture. With verification, the reviewer can confirm it directly. A stored record is useful. A verifiable record is evidence. In higher-trust environments — clinical review, financial dispute, regulator inquiry, legal hold — this distinction is the difference between an artifact the team can rely on and an artifact the team has to defend. Verification answers the integrity question before the review begins, so the conversation moves straight to the decision itself. ## 06. Where this matters in production The pattern looks the same across regulated and review-heavy industries. The decision is generated by an AI-assisted workflow. The review arrives later. The reviewer needs to retrieve the decision, not the workflow. ### Healthcare and telehealth An AI-assisted output may summarize a patient encounter, support intake, draft follow-up instructions, or assist with care operations. Reconstruction asks teams to recover patient input, retrieved clinical context, the generated summary, review state, workflow identifiers, and encounter metadata after the fact. Retrieval starts with the retained decision record for the encounter and preserves what was generated, what context was used, what controls applied, and whether the retained record still verifies. ### Banking and financial services AI-assisted workflows may support transaction review, fraud triage, dispute handling, customer response drafting, or compliance operations. Reconstruction asks teams to piece together transaction logs, account context, risk signals, model outputs, escalation history, workflow state, and validation results. Retrieval starts with the retained decision record tied to the transaction, account, case, workflow, or time range, and the team works from one stable artifact. ### Insurance AI-assisted workflows may support claims intake, coverage review, risk classification, underwriting assistance, customer communication, or appeals. Reconstruction asks teams to rebuild claim input, policy context, prior claim history, generated risk output, routing decision, review status, and retention state. Retrieval starts with the retained decision record tied to the claim, policy, workflow, and verification state. The industries differ, but the structural problem is the same. AI systems can generate useful outputs. The organization still needs retained decision evidence after those outputs affect real workflows. ## 07. What Verify is, and what it is not Obligra Verify is a decision record layer for AI-assisted workflows. It captures AI-assisted decisions at execution time and preserves them as retained records that can be retrieved by operational context and verified later. A Verify decision record preserves the input, context, prompt or request structure, model execution metadata, generated output, validation results, workflow identifiers, integrity metadata, and retention information associated with the AI-assisted decision. That is the durable evidence the rest of the stack does not produce on its own. Verify is not a model provider, a workflow orchestrator, an observability platform, a monitoring product, or a model evaluation tool. It does not replace inference, application logic, or logging. It sits above them and preserves the decision record those systems do not reliably produce. > One stable record per AI-assisted decision, preserved at execution time, retrieved by operational context, verified before review begins. ## 08. Reference summary AI-assisted decisions need a system of record because logs, traces, workflow tables, and downstream business records do not preserve the complete decision state. The reviewer who arrives later inherits a reconstruction job unless that retained record exists. A system of record for AI-assisted decisions preserves the input, retrieved context, output, execution metadata, operational identifiers, workflow state, retention metadata, and integrity reference associated with the decision. Retrieval is anchored on operational context; verification confirms the retained record still matches what was captured. Obligra Verify provides that record layer. AI-assisted decisions become retained, retrievable, and verifiable records that the customer team uses to answer review questions directly rather than by reconstruction. --- --- title: Why Retrieval Beats Reconstruction slug: why-retrieval-beats-reconstruction category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/why-retrieval-beats-reconstruction canonicalUrl: "https://obligra.ai/resources/why-retrieval-beats-reconstruction" llmTags: - llm-aligned - canonical-concept - retrieval-model - canonical-concept-source - retrieval-tier-2 --- # Why Retrieval Beats Reconstruction _AI Decision Records_ _Reviewing an AI-assisted decision after the fact comes down to two operating models. Reconstruction rebuilds the decision from logs, dashboards, tickets, screenshots, and workflow history. Retrieval starts from a decision record preserved at the moment the workflow ran. Reconstruction is structurally unreliable for AI-assisted workflows because the prompt, the retrieved context, the model behavior, and the workflow state may have all moved on since execution. Retrieval changes the shape of the review: the reviewer starts with the business identifier they already have, opens a preserved record, and verifies it before deciding what to do next._ ## 01. Overview Reviewing an AI-assisted decision weeks or months later comes down to two operating models. Either the reviewer rebuilds the decision from whatever artifacts remain — logs, dashboards, tickets, screenshots, workflow history — or the reviewer retrieves a decision record preserved at the moment the workflow ran. The first model is reconstruction. The second is retrieval. They are not different speeds of the same process. They are different architectures. > Reconstruction rebuilds evidence. Retrieval starts with preserved evidence. ![Retrieval vs Reconstruction. A split-screen visual that contrasts the two review models for AI-assisted decisions. Left column, Reconstruction: a reviewer asks a question; the reviewer must gather scattered artifacts from Logs, Dashboards, Tickets, Screenshots, and Workflow History; the reviewer performs Manual Investigation; the result is a Reconstructed Story that approximates what happened. Right column, Retrieval: a reviewer asks the same question; the reviewer retrieves a preserved Decision Record using the business context they already have; they Inspect the record, Verify its integrity, and proceed to review. Bottom callout: Reconstruction rebuilds evidence. Retrieval starts with preserved evidence.](/diagrams/obligra-verify-retrieval-vs-reconstruction.svg) * The same review question, two architectures. On the left, the reviewer assembles a story from scattered artifacts. On the right, the reviewer retrieves a record that was captured when the workflow ran. * The rest of this page walks each model in turn — what reconstruction costs the reviewer, what retrieval changes, and why verification is the property that turns a preserved record into a reviewable one. ## 02. The cost of reconstruction Reconstruction is what happens by default. A team builds an AI-assisted workflow, ships it, and only later asks where the review evidence will come from. The answer is usually some combination of logs, workflow data, tickets, and screenshots — none of which were designed to be the system of record for a decision. ![How Review Happens Without Verify. A vertical flow showing the review path when no preserved decision record exists. Stage 01 Reviewer Question: a reviewer arrives with a question about an AI-assisted decision. Stage 02 Fragmented Sources: the reviewer must gather four scattered artifacts in parallel, Logs, Workflow Data, Tickets, and Screenshots, none of which were designed to preserve the decision. Stage 03 Manual Correlation: the reviewer assembles those artifacts by hand into something that approximates the original decision, paying the assembly cost on every review. Stage 04 Review Outcome: the reviewer arrives at a conclusion based on a reconstructed approximation rather than the original retained record. Callout: Review becomes evidence gathering.](/diagrams/obligra-verify-review-without-verify.svg) * Without a retained record, review begins with evidence gathering. The reviewer pays the assembly cost on every audit, dispute, incident, and inquiry. * The artifacts that survive reconstruction were each built for a different purpose. Logs describe system activity, not decision content. Workflow data usually retains the final state of the workflow, not the state the AI-assisted step saw. Tickets capture the human-side annotations after the fact. Screenshots are snapshots of UI, not the underlying decision state. A reconstructed story may approximate what happened, but it cannot be the original captured artifact. The tradeoff is operational. Reconstruction works for a handful of decisions reviewed individually. It does not scale to audit sampling, dispute volume, regulator inquiries, or incident response — situations where the same assembly cost has to be paid again and again, on decisions that may be months apart and that depend on system state that has since moved on. GenAI-assisted workflows make reconstruction worse, not better. A generated output may depend on a prompt template, retrieved context, model configuration, provider behavior, validation logic, and workflow state that existed only at execution time. Weeks later, those conditions may no longer exist in the same form. The reviewer is asked to rebuild a decision whose original conditions have already been overwritten by the system continuing to run. ## 03. The retrieval model The architectural alternative is to preserve the decision at execution time, not to rebuild it later. A decision record captures the input, context, prompt or request structure, model execution metadata, output, validation state, operational identifiers, integrity metadata, and retention information that the workflow saw at the AI-assisted moment. Retrieval is what happens when the reviewer can start from that record instead of from logs. ![How Review Happens With Verify. A vertical flow showing the review path when a retained decision record exists. Stage 01 Business Identifier: the reviewer arrives with the case, transaction, encounter, or workflow identifier their team already uses. Stage 02 Decision Record: the business identifier resolves to the preserved decision record captured at execution time. Stage 03 Inspect: the reviewer reads the captured content, lifecycle state, and review history. Stage 04 Verify: the reviewer confirms the retained record still matches what was captured at the original AI-assisted moment. Stage 05 Review: the reviewer uses the verified record inside the customer-side audit, operations, risk, or compliance workflow. Callout: Review begins with a preserved record.](/diagrams/obligra-verify-review-with-verify.svg) * With a retained record, review begins with the business identifier the reviewer already has. The record is the starting point, not the result of an investigation. * The shape of the work changes. The reviewer arrives with a business identifier — a case, transaction, encounter, or workflow ID — rather than a log query or a trace ID. The identifier resolves to the preserved decision record. The reviewer inspects the captured content alongside its lifecycle state, verifies the record against what was originally captured, and proceeds into the customer-side audit, operations, risk, or compliance workflow. The reviewer does not re-run the system. They do not approximate prior state. They do not stitch logs together to construct a narrative. The record was preserved when the workflow ran, and retrieval is how it returns to the surface. ## 04. Why verification matters Preserving a record is not enough on its own. Reviewers arriving later need a way to confirm that the record they retrieve is the record that was originally captured. Verification is that property. ![Why Verification Matters. A five-stage horizontal flow showing how verification closes the trust loop on a retained decision record. Stage 01 Original Decision: an AI-assisted decision is produced inside the customer workflow. Stage 02 Retained Record: the decision is preserved at execution time as a retained decision record. Stage 03 Retrieved Record: a reviewer arrives later and retrieves the record using the business identifier their team already uses. Stage 04 Verification: the system confirms that the retrieved record still matches what was captured at the original AI-assisted moment. Stage 05 Reviewer Trust: the reviewer proceeds with confidence that the artifact under review is the artifact that was captured. Verification is the property that turns a preserved record into a reviewable record.](/diagrams/obligra-verify-why-verification-matters.svg) * Verification closes the loop between the retained record and the retrieved record. The integrity question is answered before the review begins. * Without verification, the reviewer is asked to trust that the retrieved record still matches the original capture. With verification, the reviewer can confirm it directly. Reviewers spend their time on the decision itself rather than on whether the artifact is trustworthy. This is the property that turns a preserved record into a reviewable one. A retrieved record without an integrity check is a stronger starting point than a reconstructed story, but it is still a claim. A retrieved record paired with a verification result is evidence. ## 05. Where this matters in production The retrieval-versus-reconstruction tradeoff plays out differently in different industries, but the operational pattern is the same. Reviewers arrive with the business identifier their team already uses, and the review either begins with a retained record or begins with an assembly job. ### Healthcare In healthcare and telehealth workflows, an AI-assisted output may summarize a patient encounter, support intake, draft follow-up instructions, or assist with care operations. Reconstruction asks teams to recover patient input, retrieved clinical context, the generated summary, review state, workflow identifiers, and encounter metadata after the fact. Retrieval starts with the retained decision record for the encounter, which preserves what was generated, what context was used, what controls applied, and whether the retained record still verifies. ### Banking and financial services In banking and financial services, AI-assisted workflows may support transaction review, fraud triage, dispute handling, customer response drafting, or compliance operations. Reconstruction asks teams to piece together transaction logs, account context, risk signals, model outputs, escalation history, workflow state, and validation results. Retrieval starts with the retained decision record tied to the transaction, account, case, workflow, or time range, and the team works from one stable artifact rather than a cross-system reconstruction. ### Insurance In insurance, AI-assisted workflows may support claims intake, coverage review, risk classification, underwriting assistance, customer communication, or appeals. Reconstruction asks teams to rebuild claim input, policy context, prior claim history, generated risk output, routing decision, review status, and retention state. Retrieval starts with the retained decision record tied to the claim, policy, workflow, and verification state, which gives claims, compliance, audit, and legal teams a clearer basis for review. The shared pattern across all three is straightforward. The problem is not that AI systems cannot generate useful outputs. The problem is that organizations need retained decision evidence after those outputs affect real workflows. ## 06. What retrieval gives compliance and audit teams For compliance, audit, legal, and risk teams, retrieval changes the review model. Instead of asking engineers to rebuild what likely happened, reviewers can request the retained decision record — an artifact that already carries the input, context, output, workflow metadata, validation state, integrity metadata, and retention information associated with the AI-assisted decision. The distinction matters most in regulated and review-heavy workflows. A compliance team needs more than a narrative. An auditor needs more than a log trail. A legal team needs more than a reconstructed approximation. They need a retained record that can be retrieved, reviewed, and verified. A reconstructed explanation may help tell the story. A retrieved decision record provides the evidence. ## 07. Recommended approach Teams that already run AI-assisted workflows in production tend to converge on the same operating practices once retrieval is available. The practices below are the ones worth standardizing on early, rather than discovering during the first audit or dispute. - Capture the decision at execution time. Do not rely on later log assembly to recover what the workflow saw. - Anchor retrieval on the business identifier the reviewer already uses — case, encounter, transaction, claim, workflow — not on internal record IDs or trace IDs. - Read lifecycle state and verification state before debating the content of the output. The state determines how much trust can be placed in what comes next. - Treat verification as part of review, not as an optional step. The integrity question should be answered before the decision is reopened. - Use one stable record model across cloud, hybrid, and on-prem deployments. The runtime can vary; the record shape should not. - Train audit, operations, risk, legal, and engineering teams to work from the same retained record. Shared retrieval surface, shared review surface. ## 08. Reference summary Reconstruction is the process of rebuilding a past AI-assisted decision from logs, traces, prompts, workflow state, provider history, tickets, screenshots, and memory. Retrieval is the process of accessing the retained decision record captured when the AI-assisted decision occurred. In GenAI-assisted workflows, reconstruction is structurally unreliable because prompts, retrieved context, model behavior, validation state, workflow state, and system configuration may change after execution. Verification closes the integrity loop on the retained record so the retrieved artifact can be trusted as the artifact that was captured. Obligra Verify provides the decision record layer that makes retrieval the default operating model: records are preserved at execution time, retrieved by operational context, inspected alongside their lifecycle state, and verified before review begins. --- --- title: Working with Decision Records in Verify slug: working-with-decision-records category: Fundamentals retrievalTier: 2 retrievalRole: canonical canonical: true lastUpdated: 2026-08-20 href: /resources/working-with-decision-records canonicalUrl: "https://obligra.ai/resources/working-with-decision-records" llmTags: - llm-aligned - canonical-concept - integration - canonical-concept-source - retrieval-tier-2 --- # Working with Decision Records in Verify _Workflow_ _Organizations rarely struggle to create AI-assisted decisions. They struggle to review them later. Weeks or months after a workflow runs, audit, compliance, fraud, risk, security, operations, and legal teams need to answer questions about what the system produced, what context surrounded the decision, what controls applied, and whether the record under review can still be trusted. Working with decision records in Verify begins with those review questions. The page is about how reviewers find records, what they see when they open one, how they confirm the record still reflects what was captured, and how a single record supports audit, operations, risk, and compliance workflows without forcing teams to reconstruct the decision from logs, screenshots, and tickets._ ## 01. Overview Organizations rarely struggle to create AI-assisted decisions. They struggle to review them later. Weeks or months after a workflow runs, an audit team arrives with a sample to review, a fraud analyst reopens a disputed transaction, an incident responder needs to understand what the system did during a window, or a clinical reviewer needs to look at a recommendation that ended up in a patient encounter. In every one of those situations, the question is some variant of the same four: what did the system produce, what context surrounded the decision, what controls applied, and can we still trust the record under review? In most environments today, those answers do not arrive as a single object. They are assembled from logs, dashboards, workflow tables, screenshots, tickets, and application data — and the cost of that assembly is paid every time review happens. Verify changes the operating model. The decision is preserved as a structured record at the moment of execution, so later review starts from a stable artifact rather than a collection of clues. > With Obligra Verify, review starts from business context and a preserved decision record — not from logs, screenshots, and partial workflow evidence. ![Working with Decision Records in Verify. A seven-step horizontal flow showing how an AI-assisted decision becomes a reviewable artifact. Step 01 AI-Assisted Workflow: an AI-assisted step runs inside the customer workflow. Step 02 Capture: selected decision context is captured at the moment of execution. Step 03 Decision Record: the captured context becomes a retained decision record. Step 04 Retrieve by Business Context: reviewers find the record using business identifiers such as case ID, transaction ID, encounter ID, or workflow ID. Step 05 Inspect: the reviewer opens the record and reads its captured context, lifecycle state, and review history. Step 06 Verify: the reviewer confirms the retained record still matches what was captured at the original AI-assisted moment. Step 07 Review: the reviewer uses the verified record in the customer-side audit, operations, risk, or compliance workflow. Three architecture callouts anchor the flow: review begins with business context; verification confirms record integrity; records support audit, operations, risk, and compliance workflows.](/diagrams/obligra-verify-working-with-decision-records.svg) * The end-to-end shape of working with a decision record. Capture happens once. Retrieval, inspection, verification, and review happen whenever the customer team needs to look at the decision again. * ## 02. What a decision record represents A decision record is the reviewable record of an AI-assisted outcome. It is related to the output the workflow produced, but it is not the same thing as the output artifact itself. The output may be a visit summary, a case recommendation, a transaction classification, an approval recommendation, or a customer response draft. The decision record captures the surrounding facts a reviewer will need months later to understand that output — the workflow that produced it, the case or encounter or transaction it belongs to, the context the workflow saw, what was reviewed or overridden, whether required checks passed, and whether the stored record still verifies. In practice, that framing is what separates a decision record from a log entry. A log captures the fact that something happened. A decision record captures enough about what happened that a reviewer arriving later can inspect it without going back to the workflow itself. ## 03. How organizations usually work before Verify Most customers do not begin with a dedicated record layer. They begin with a working AI-assisted workflow running somewhere in their stack — in a public cloud, in a hybrid deployment, in an on-prem data center, calling a commercial model API directly, routing through an internal gateway, or running behind a managed platform. The runtime environment varies. The review problem does not. A common pattern looks the same across deployments. An application collects the business context for a request. A service builds the request to the model. The model returns an output. The workflow stores, routes, or displays the result. And different systems record different pieces of what happened — rarely with a clean line back to the single artifact that was the decision. That approach is common because it is enough to get a feature into production. It is also the point where later review usually becomes expensive. Workflow state, routing decisions, policy conditions, reviewer action, and output integrity tend to be absent or distributed across different systems, and the cost of stitching them back together is paid every time someone needs to review a decision. Verify does not replace that runtime. It adds the record layer that most teams are missing — one artifact per decision, preserved at the moment the decision is made. ## 04. How users locate a decision record in Verify The starting point for retrieval matters more than any other operational decision a customer team makes about working with Verify. Most reviewers — compliance, audit, fraud, risk, security, clinical operations, platform engineering, legal, dispute response, product operations — do not begin with prompt text or trace IDs. They begin with the business object they already have. That object is some combination of a case ID, an encounter ID, a transaction ID, a workflow ID, a reviewer name, a source application, or a date range. Those identifiers are what reviewers already use to talk about the work being performed, and they are the identifiers retrieval should be anchored on. Verify is best used as a business-context retrieval system, not as another log explorer. ![How Reviewers Find Records in Verify. The diagram shows the funnel from business identifiers to a matching decision record. Top row, six business identifier chips arranged horizontally: Case ID, Transaction ID, Encounter ID, Workflow ID, Reviewer, Date Range. These identifiers funnel down into the Verify Search box. Verify Search returns a Matching Decision Record. The reviewer then takes three downstream actions on the record: Inspect the captured content and lifecycle state; Verify the integrity of the retained record against what was captured; Review the verified record inside the customer-side audit, operations, risk, or compliance workflow.](/diagrams/obligra-verify-how-reviewers-find-records.svg) * Retrieval begins with the business identifier the reviewer already has. The same identifiers customer teams already use to talk about work are the identifiers that resolve to a record. * In practice, the search flow is short. The reviewer starts with the business identifier they already have, narrows by workflow, source system, lifecycle state, reviewer, or time range if needed, opens the matching decision record, and reads the record header, lifecycle state, and verification result first. Only then do they inspect the captured decision details, context, and review history. ## 05. What users should expect to see in a decision record A decision record is a single artifact with a structured interior — structured enough to support both human review and downstream controls. The structure is what makes the record usable later: a reviewer gets enough context to understand what happened without going back to runtime systems to fill in the gaps. ![What is inside a Decision Record. The diagram shows a retained decision record as a single artifact, with its internal anatomy expanded into seven labelled sections. Section 01 Record Identity: stable identifiers including decisionRecordId, environment marker, created timestamp, and storage references that uniquely place this record in the corpus. Section 02 Workflow Context: workflowId and operational context such as case ID, encounter ID, transaction ID, claim ID, or policy ID, used for retrieval by reviewers later. Section 03 Prompt: the request, instructions, and retrieved context the AI-assisted workflow saw at the time of execution. Section 04 Response: the AI-assisted output, classification, recommendation, summary, or draft that affected the workflow. Section 05 Review History: human reviewer actions, overrides, releases, and timestamps that capture what a human did with the AI-assisted output. Section 06 Validation State: whether the record passed required structural and policy checks before it moved further in the workflow. Section 07 Verification State: the integrity result, confirming whether the retained record still matches what was captured at the AI-assisted moment.](/diagrams/obligra-verify-inside-a-decision-record.svg) * The seven sections inside a retained decision record. Reviewers read the header first — identity, workflow context, and verification state — before opening the captured decision content. * The reading order matters as much as the structure. A reviewer opens the record header first to confirm what is under review — the record identity, the workflow context, and the verification state. They read the lifecycle state next to understand where the record is in its workflow. Then, and only then, do they inspect the captured prompt and response and the review history. That ordering protects review confidence by establishing trust in the artifact before debating the content of the output. For the field-by-field reference of every section in a decision record, see [Structure of a Decision Record](/resources/structure-of-a-decision-record) . ## 06. How to read the major record states A retained decision record carries lifecycle state alongside its captured content. Reviewers read the state before they read the content, because the state determines how much trust can be placed in what comes next. The states below are the ones reviewers encounter most often. ### Recorded A structured decision record exists and is linked to the workflow output. The decision has been captured as a first-class object rather than left behind in logs, tickets, or application history. ### Validated The record passed the required checks before it moved further in the workflow. Validation usually covers structural completeness — required fields, data shape — and policy compliance, which checks whether the record met the release or control requirements the workflow demanded. ### Attested An accountable signer has bound itself to the record. The record has moved beyond simple storage and into a stronger trust state that supports the integrity checks reviewers rely on later. ### Verified A later integrity check confirmed that the record under review still matches the preserved record. This is the state that matters most when a reviewer asks the question that opens almost every after-the-fact review: are we still looking at the original record? ### Superseded, blocked, revoked, or replaced These states show that the record lifecycle has changed after capture. A record may be replaced by a later version, blocked by policy, revoked during review, or superseded by a corrected outcome. Verify preserves that history so the reviewer can see what changed, when it changed, and what the current state means in context. ## 07. Common review workflows Customer teams use Verify in a small number of recognizable review workflows. The shape is similar across them — a reviewer arrives with a business identifier, retrieves the record, inspects it, verifies it, and acts inside the customer-side review process. What changes is the question the reviewer brings to the record. ### Fraud and transaction dispute review Fraud and risk teams arrive with a transaction, an account, an alert, or a review case. The questions are business-facing from the start: why was this transaction flagged, why was it routed this way, what recommendation or score was produced, was a reviewer involved, and can the preserved record for that decision be shown? Without Verify, the answer comes together from several systems. With Verify, the team retrieves the record directly and works from one artifact that already carries the workflow linkage, preserved context, recorded output, review history, and current verification state. ### Audit and compliance review Audit and compliance teams arrive with a case sample, a workflow sample, a policy review set, or a time window. They need more than proof that a model was active — they need a reviewable record tied to a specific business event. The reviewer retrieves the decision record directly and works from a structured object that already includes its lifecycle state, control context, and verification result, instead of reconstructing the event from logs and provider history. ### Incident response and security review Security teams, platform teams, and incident responders need a fixed starting point when an AI-assisted workflow is part of an incident. The first questions are about what the system actually did, what was produced, what context surrounded the decision, and whether anything changed after the fact. The incident team begins with the preserved decision record — one retained object tied to the workflow, with captured context, lifecycle and review state, and a verification result that shows whether the record still matches the preserved version. ### Human-in-the-loop approvals Many enterprise workflows use AI to recommend, classify, route, summarize, or draft, while a human makes the final call. The most useful review question in those workflows is rarely “what was finally approved?” alone — it is also “what did the system recommend, what did the reviewer change, and what was released?” Verify preserves the AI recommendation before the human action changes the final outcome, which gives the customer a much clearer picture across review, management oversight, audit, product feedback, and engineering analysis. The pattern across all four is the same. The reviewer arrives with business context, retrieves the record, inspects it, verifies it, and acts. The retrieval surface stays consistent; only the review question changes. ## 08. Model-agnostic and cloud-agnostic operation Organizations rarely standardize on one model provider or one cloud platform forever. Over time, workloads move, models change, and deployment patterns evolve. A workflow that runs through one provider today may run through a different provider next year, or through a managed inference gateway that routes across more than one. The runtime that produces the decision can change for reasons that have nothing to do with the record layer. Verify is designed to operate above the runtime environment, not inside one vendor’s stack. The record layer is intentionally stable across the kinds of change customer teams routinely encounter — provider changes, cloud changes, hybrid and on-prem deployments, and gateway rearchitectures. The runtime can vary. The preserved record stays in one stable structure. That property matters because the cost of working with decision records compounds quickly when the record shape itself drifts every time the runtime changes. By holding the record shape constant, Verify lets a single review program span a portfolio of AI-assisted workflows that do not look alike at the model or runtime layer — one review surface, one retrieval pattern, one verification discipline across all of them. ## 09. What Verify helps prove, and what it does not prove Verify is intentionally scoped. It helps customer teams show that a decision record was captured, preserved, reviewed in context, checked against required controls, attested, and verified later as the retained record under review. That scope is what makes the retrieval-and-review surface trustworthy — reviewers know what the record claims and what it does not. The properties Verify does not assert are equally important to be explicit about. Verify does not prove that the model made the best possible recommendation, that the decision was fair by default, that the workflow logic was well-designed, that the source data was complete or unbiased, or that the final human judgment was automatically correct. Those questions belong to the customer team’s own review program. What Verify provides is a much stronger record of what happened, what controls applied, and whether the preserved record still matches the original captured object — the foundation the customer team’s review program operates on. ## 10. Recommended operating practices Customer teams get the most value from Verify when they treat it as part of the review workflow, not as another system screen. The practices below are the ones customer teams converge on after their first production review. - Start retrieval from business context — case, encounter, transaction, workflow, or time range — not from prompt text, trace IDs, or internal record IDs. - Read lifecycle state before debating the content of the output. The state tells the reviewer how much trust can be placed in what comes next. - Use one stable record model across cloud, hybrid, and on-prem environments. The runtime can vary; the record shape should not. - Preserve the original AI recommendation before human edits in approval workflows. The recommendation, the change, and the final outcome together are usually more useful than any one of them alone. - Train audit, operations, risk, legal, and engineering teams to work from the same decision record. Shared retrieval surface, shared review surface. - Use verification results to confirm record integrity before formal review begins. Confidence in the artifact comes before confidence in the content. --- --- title: API Key Placement and Secret Storage slug: api-key-placement-and-secret-storage category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/api-key-placement-and-secret-storage canonicalUrl: "https://obligra.ai/resources/api-key-placement-and-secret-storage" llmTags: - llm-aligned - architecture-core - trust-security - retrieval-tier-3 - supporting-reference --- # API Key Placement and Secret Storage _Architecture_ _The Verify API key is the credential that authorizes a customer runtime to submit retained decision records, and where it lives is one of the load-bearing decisions in any integration. Organizations consistently discover during their first security review that this single decision — where the key is stored, which runtimes can read it, how it rotates — sets the security posture for the entire Verify integration. Keys belong inside trusted server-side runtimes, read from a customer-side secret manager, separated by environment, and rotated when exposure is suspected; everything else about how the integration is shaped follows from that._ ## Overview Verify API keys are environment-scoped credentials that authorize a trusted customer backend to submit retained decision records against a specific environment — Sandbox or Production. They are issued from the Verify Console, shown once at creation, and used as a request header on every server-side capture call. In practice, the way customer teams handle these keys is the first thing a security reviewer asks about, and the first place an integration can erode trust without anyone noticing. The customer team owns where these keys live, who can read them, and how they are rotated. The Verify platform issues and validates the key; everything else about how the key is held, distributed, and used at runtime is customer-side architecture — which means the controls customer teams already apply to other production credentials transfer directly here. > Treat each Verify API key like a database password. > > > > > Its handling determines the security posture of the entire customer integration. The decisions made on this page are the foundation reviewers, auditors, and security teams will inspect first. ## API key placement is a trust boundary decision The Verify capture surface is built around a clear trust boundary: the customer backend submits retained decision records on behalf of the customer’s AI-assisted workflows, and the API key is the credential that asserts that authority. The tradeoff embedded in this design is intentional — the customer team holds the credential, which means the customer team also holds the responsibility for where it lives and who can read it. Verify does not mediate that placement. Where that key lives is therefore not just a credential- management detail. It is an architectural choice with downstream consequences. Placement determines which runtimes are allowed to act as the customer backend for capture, and which are explicitly outside the trust boundary. It determines which downstream review surfaces will see records authored against a given key — Sandbox or Production, never both. It determines which customer-side controls (secret-manager access policy, role-based access, network egress restrictions) gate access to the capture surface. And placement determines which audit trail customer security teams can rely on later: who held the credential, which workloads used it, when it was rotated, and how exposure was handled when the trust boundary was suspected to have weakened. When the placement decision is right, the trust boundary holds even when an application server is compromised, an engineer changes roles, or a third party reviews the customer’s AI-assisted workflows months later. When it is wrong, every retained decision record produced against the exposed key carries the weakened boundary forward. In current Verify deployments, the operational trust boundary is no longer a single decision about where the credential lives. It is the combination of four customer- operated controls: **API key placement**, the **Customer-Owned Proxy**, the **Capture Decision Policy**, and the **Field Retention Policy**. Together those four controls determine which systems may submit records to Verify, which interactions become retained decision records, and which fields are allowed to leave the customer environment. The rest of this page focuses on the credential-placement half of that boundary; the other three controls are covered in the architecture references linked at the bottom of the page. ![API Key Trust Boundary. Four customer-operated controls shown side by side inside a teal-bordered boundary frame labeled OPERATIONAL TRUST BOUNDARY · CUSTOMER-OPERATED. Control 01 API Key Placement: read from a customer-controlled secret manager at process start, held in process memory only; determines which runtime may submit records; environment-scoped credential. Control 02 Customer-Owned Proxy: trusted runtime that holds the credential and evaluates the customer's capture policies; determines where the credential and policies live; same access policy, same audit trail. Control 03 Capture Decision Policy: per-interaction governance control with Capture and Skip outcome chips; determines which interactions become records; evaluated before transmission. Control 04 Field Retention Policy: per-field governance control with Allow, Redact, Truncate, and Drop action chips; determines which fields leave the environment; approved fields only cross the boundary. Footer annotation: the credential, the proxy, and the two policies live in the same trusted runtime, under the same access policy, with the same audit trail; the trust posture of every retained decision record depends on all four working together.](/diagrams/obligra-verify-api-key-trust-boundary.svg) * Four customer-operated controls form the operational trust boundary for Verify integrations. The credential, the proxy, and the two policies live in the same trusted runtime. Together they determine which systems may submit, which interactions become records, and which fields may leave. * ## Where API keys belong Verify API keys belong inside the trusted server-side runtime that performs capture — read from a customer-controlled secret manager or secure runtime configuration source at process start. ### Recommended storage approaches - **Cloud secret manager** — AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, or equivalent. Access scoped by role, audited centrally, rotated through the customer's existing secret-management workflow. - **Runtime environment variable** — Injected by the customer's deployment system at process start from a secret manager or CI/CD secret store. The runtime never reads from disk; the value is in process memory only. - **CI/CD secret store** — GitHub Actions secrets, GitLab CI variables, CircleCI contexts, or equivalent — for build-time injection into runtime environments. Source-of-truth remains in the customer's secret manager; the CI store is a controlled propagation step. - **Customer-side configuration service** — A customer-controlled configuration service that exposes secrets to authorized runtimes only, with the same access control and audit posture as a secret manager. The exact choice depends on the customer’s existing secret-management program. The architectural requirement is the same across all four: the key is held by a customer- controlled system, available only to the trusted runtime, and never leaves that boundary. ## API keys and the customer-owned capture boundary In governed deployments, the Verify API key typically does not sit directly inside the application runtime. Instead, it resides inside the Customer-Owned Proxy that the customer operates between their workflows and the Verify API. That proxy becomes the trusted runtime responsible for submitting retained decision records to Verify on behalf of the application. It is also the place where the customer’s capture policies are evaluated — so governance controls run before any information is transmitted and before the credential is used to author a record. The result is that the credential and the governance controls live in the same trusted runtime, under the same access policy, with the same audit trail. Applications no longer need to hold the Verify key, and the key’s authority to author records is scoped to traffic that has already passed the customer’s capture and field retention policies. For deeper architecture detail on where the proxy sits and how it relates to the rest of the deployment, see [Deployment Topology](/resources/deployment-topology) , [Customer Integration Patterns](/resources/customer-integration-patterns) , and the [Server-Side Capture Pattern](/resources/server-side-capture-pattern) . ## Where API keys must never appear The locations below are explicitly outside the trust boundary for Verify capture. A key that lands in any of them should be considered exposed and rotated. - Frontend JavaScript bundles, single-page applications, or any browser-side runtime. - Mobile applications, embedded clients, or other untrusted runtimes. - Source control — even in private repositories. Once committed, the key persists in history and propagates to every clone. - Plaintext configuration files committed to any artifact store, container image, or release bundle. - Screenshots shared in chat, tickets, support correspondence, or internal documentation. - Application logs, APM events, error trackers, or third-party log infrastructure. - Issue trackers, design documents, knowledge bases, or any shared collaboration surface. - Test fixtures, integration-test data, or example payloads checked into source control. > Do not expose Verify API keys in browser applications, mobile binaries, or public repositories. > > > > > If exposure is suspected, rotate the key immediately and review the retained decision records captured during the exposure window. The rotation process is described later on this page. ## Sandbox and Production separation Verify API keys are environment-scoped. A Sandbox key cannot submit Production records, and a Production key cannot submit Sandbox records. The customer-side architecture should preserve that separation end-to-end. In practice this means generating distinct keys per environment, storing them under distinct secret-manager paths or namespaces, and scoping read access by environment so that engineers, services, and CI/CD runners only see the credentials they legitimately need. Each runtime then receives the key for its environment and confirms the active environment at process start before the first capture call. The downstream review surfaces stay environment-aware in the same way — distinct dashboards, distinct queues, distinct retrieval surfaces — so a Sandbox record can never flow into Production review. For deeper customer-side guidance on environment discipline across capture, retrieval, verification, and rollout, see the [Environment Strategy](/resources/environment-strategy) architecture page. ## Reading keys at runtime The customer backend reads the Verify API key once per process start (or per refresh cycle if rotation is active) and holds it in process memory. The key is then attached as the standard header on every server-side capture call. ### Header shape ```text X-Verify-Api-Key: ``` ### Runtime patterns The runtime reads the key once from the customer’s secret manager (or environment-injected secret store) and caches it in process memory for the lifetime of the process. If the customer’s secret-management program supports rotation with refresh, the runtime periodically re-reads the key so a rotation event is picked up without restart. The in-memory value is treated as a secret. It is never passed as a constructor argument that ends up in stack traces, never concatenated into log strings, and never included in error messages. The credential is applied as a request header rather than a query-string parameter, since query strings show up in proxy logs, CDN logs, and browser histories. On retries, the runtime reuses the same in-memory value. Re-reading from the secret manager on every retry adds load on the secret manager and does not improve security. ### Console and authenticated workflows Authenticated user and console workflows use a bearer token instead of the API key: ```text Authorization: Bearer ``` Bearer tokens carry their own customer-side handling requirements — they are session-scoped, should expire, and should never be persisted alongside API keys. The placement guidance on this page applies primarily to API keys used for server-side capture. ### Trusted runtime, not just key holder In governed deployments, the trusted runtime that holds the credential is also the runtime that evaluates the customer’s capture policies. The Customer-Owned Proxy uses the **Capture Decision Policy** to decide whether a given interaction should be captured or skipped, and the **Field Retention Policy** to decide which fields are approved for transmission to Verify. Only after both policies have been evaluated does the runtime apply the API key and submit the approved record. The credential and the governance decisions therefore live in the same trusted runtime under the same access controls. For policy structure, evaluation order, and the configuration model, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## Rotation and exposure handling Rotation is the customer-side process of replacing an active API key with a new key. The Verify Console supports issuing new keys and revoking old keys. The customer team decides cadence, automation, and how rotation coordinates with running workloads. ### Planned rotation - Issue the new key from the Verify Console. Store it in the customer's secret manager alongside the existing key (overlap window). - Roll the new key into running workloads — through deployment, secret-refresh, or runtime re-read. - Confirm that running workloads are submitting against the new key before retiring the old one. Customer-side observability around capture should show the cutover. - Revoke the old key from the Verify Console once the cutover is complete. The revocation is final — the old key cannot submit further records. - Document the rotation in the customer's audit log so reviewers can see when the cutover occurred and which records were captured under which key. ### Suspected exposure - Rotate the key immediately — issue a new key, roll it into running workloads, and revoke the suspected-exposed key. - Treat the exposure window as the period from the last known-good state to the rotation cutover. - Review retained decision records captured during the exposure window — confirm they were generated by legitimate customer workflows. - Notify the customer's internal security and audit teams using the customer's existing incident-response process. - Treat the rotation as part of the incident record. Document who rotated, when, and the outcome of the exposure review. Rotation cadence is a customer-side decision. The Verify platform does not require a specific rotation interval — customer teams should align with their existing secret-management program and the customer’s compliance obligations. ## Logging and observability around credentials Customer-side observability around capture is valuable — but every log line that leaves the trusted runtime is a potential exposure surface for the credential that authorized the call. The logging discipline below preserves the trust boundary. ### Safe to log - Environment — Sandbox or Production, so log queries can be scoped per environment. - Capture outcome — success, retryable failure, non-retryable failure, or timeout. - Retry attempt count — to surface retry storms or pathological backoff behavior. - decisionRecordId when returned — useful for correlating customer-side investigation with retained records. - Operational identifier reference (claimId, encounterId, transactionId, etc.) — for correlation with the customer's authoritative systems. - Key reference, not key value — for example, a short non-reversible identifier for the active key ("prod-v3"), never the key itself. ### Must not be logged - The raw API key value — anywhere, at any log level, by any logger that can ship to long-term log infrastructure. - The Authorization header on bearer-authenticated calls — bearer tokens are credentials too. - Full request headers — request-logging middleware should redact authentication headers before any log line is emitted. - Stack traces that include credential-bearing arguments — review error-handling code paths to ensure secrets are not concatenated into error messages. - Curl reproductions in support correspondence — strip the credential before sharing. ## Common mistakes The mistakes below are the credential-handling patterns that surface most often during onboarding and Production rollout. They are listed not because they are exotic, but because they are the patterns that weaken the trust boundary in ways that reach retained decision records months later. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Hardcoding API keys in source code | Keys committed to source control are long-lived credential leaks even in private repositories — and persist in history after deletion. | Read keys from a secret manager at process start. Never commit credentials to any source control history. | | Sharing one key across Sandbox and Production | Cross-environment key reuse breaks the environment boundary and makes incident response harder — a single rotation impacts both environments simultaneously. | Distinct keys per environment, stored in distinct secret-manager paths, with environment-scoped access. | | Embedding the key in a frontend or mobile build | Frontend bundles, mobile binaries, and any artifact shipped to end-user devices are outside the trust boundary. The key becomes effectively public once shipped. | Frontend and mobile clients call the customer backend, which submits to Verify with the server-side key. | | Passing the key as a query-string parameter | Query strings show up in proxy logs, CDN logs, browser histories, and bookmarks — creating exposure surfaces that headers do not. | Always apply the key as the X-Verify-Api-Key request header. | | Logging the raw key for debugging | Application logs are routinely shipped to long-term log infrastructure where retention, access, and audit are different from the runtime environment. | Log a non-reversible key reference (for example, "prod-v3") when correlation is needed. Never log the value. | | Skipping rotation after a suspected exposure | An exposed key continues to authorize record creation until it is revoked. Every retained decision record captured during the exposure window carries the weakened boundary forward. | Rotate immediately on suspected exposure, review records captured during the window, document the incident. | | Reading the secret from the secret manager on every call | Adds latency and load on the secret manager without improving security. The key is already in process memory after the first read. | Read the key once at process start (or per refresh cycle if rotation is active); cache in process memory; reuse across calls. | ## Validation checklist Promotion from Sandbox to Production is a moment where a single missed credential control can compromise the trust boundary later. The checklist below is a final pass that confirms the credential-handling discipline is in place before Production traffic begins flowing through the integration. Before promoting a Verify integration: - API keys are stored in a customer-controlled secret manager (or equivalent secure runtime configuration source), not in source control. - Per-environment keys exist — distinct Sandbox and Production credentials, with no shared use. - Secret-manager access is scoped by role — only the runtimes and engineers that legitimately need the credential have read access. - Runtimes read the key at process start and cache it in process memory — not on every call. - The key is applied as the X-Verify-Api-Key request header — never as a query-string parameter. - Application logs, APM events, and error trackers redact the API key and the Authorization header before shipping. - A rotation process is documented — both planned rotation and suspected-exposure rotation, with revocation steps. - The customer's incident-response process covers credential exposure for the Verify integration. - An audit trail is in place — secret-manager access logs, rotation history, and customer-side capture observability are aligned. - Frontend, mobile, and other untrusted runtimes do not have access to the key under any code path. ## Related documentation The pages below cover the architectural decisions credential placement depends on most directly: the governance boundary that holds the credential, the environment discipline that scopes it, and the deployment shape that gives it a home. - [Install and Configure Verify — canonical first-time developer onboarding loop, including secret-storage guidance in Step 3.](/resources/install-and-configure-verify) - [Server-Side Capture Pattern — the trusted server-side topology Verify keys belong inside.](/resources/server-side-capture-pattern) - [Deployment Topology — where the Customer-Owned Capture Boundary sits and how the credential, proxy, and policies are placed inside it.](/resources/deployment-topology) - [Customer Integration Patterns — the integration shapes (direct, governed, proxy-fronted) that determine where the credential ultimately lives.](/resources/customer-integration-patterns) - [Configuring an AI Capture Policy — Capture Decision Policy and Field Retention Policy, the governance half of the operational trust boundary.](/resources/configuring-an-ai-capture-policy) - [Environment Strategy — Sandbox vs Production separation discipline across the full capture-and-retrieve loop.](/resources/environment-strategy) - [Operational Context Mapping — how customer business identifiers map onto the retained decision records the key authorizes.](/resources/operational-context-mapping) - [Verify API Reference — first-time-user API reference including the customer-visible authentication patterns.](/resources/api-reference) - [Verify SDK Reference — capture SDK methods and environment-aware onboarding, including security requirements.](/resources/verify-sdk-reference) - [Customer Security Overview — broader customer-side security posture around Verify integrations.](/resources/security-overview) --- --- title: API Reference slug: api-reference category: Developers retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/api-reference canonicalUrl: "https://obligra.ai/resources/api-reference" llmTags: - llm-aligned - integration - retrieval-tier-3 - supporting-reference --- # API Reference _Developers_ _The Verify API is intentionally narrow: it captures retained decision records, retrieves them by operational context, supports inspection and verification, and exposes the credential and activity surfaces customer teams need around those operations. In practice, this page reads as both a first-time onboarding guide and an API reference — opinionated where opinionated guidance helps (start in Sandbox, capture from a trusted server-side runtime, retrieve by operational context, validate end-to-end before Production), and precise where precision matters (payload shape, error model, retry posture, environment separation). The tradeoff is the one most API references make: enough teaching to integrate confidently, enough reference to operate confidently afterwards._ ## Overview The Verify API helps customers capture, retrieve, inspect, and verify retained decision records for AI-assisted operational workflows. Use this page to understand the core API workflow, create your first server-side capture integration, retrieve records by operational context, and validate your setup before moving from Sandbox to Production. In plain customer language, Verify works like this: - Verify captures retained decision records from AI-assisted operational workflows your teams already run. - Each retained decision record supports later review — by claims, compliance, audit, quality, fraud, legal, or operations teams. - Records are retrieved later using operational context — the same business identifiers your teams already use (claimId, encounterId, transactionId, escalationId, and so on). - The Verify API is built for operational workflows, not generic application logging or telemetry. - API keys are used for server-side capture. Bearer tokens are used for console and authenticated user workflows such as retrieval, inspection, verification, API-key management, and reviewing activity. > Start small. Validate the loop end-to-end. > > > > > Most customers should begin by capturing one Sandbox decision record, retrieving it by operational context, and verifying it before expanding the integration. ## How Verify works Verify is a system of record for AI-assisted decisions. The customer workflow is short and predictable: - Capture — a retained decision record is created from the AI-assisted workflow output. - Retrieve — the record is later found using operational identifiers the customer team already uses. - Inspect — the record is opened in the Verify Console (or via API) to review what was captured. - Verify — verification produces a review-time signal when the record needs to be reviewed. ### Platform workflow ```text Customer Application │ ▼ Customer Backend │ ▼ (Optional) Customer-Owned Proxy │ ▼ Verify API │ ▼ Decision Record │ ▼ Verify Console │ ▼ Verification │ ▼ Evidence & Review ``` Understanding the lifecycle above makes the rest of this reference easier to read — endpoints map directly onto these steps. A first-time customer should be able to capture, retrieve, inspect, and verify their first decision record by following the page top to bottom. ## Choose your integration pattern Pick the integration pattern that matches the workload being integrated. The same Verify API is reachable from both patterns — the difference is where capture and field retention policy run. | Scenario | Recommended pattern | | --- | --- | | Evaluating Verify | SDK direct | | Builder onboarding | SDK direct | | Internal tools | SDK direct | | Production applications | Customer-owned proxy | | Governance programs | Customer-owned proxy | | Regulated workloads | Customer-owned proxy | | AWS-first deployments | CloudFormation or Terraform | - Use SDK direct when the priority is the fastest possible loop to a working integration — evaluation, Builder onboarding, internal tools, sandboxing. - Use a customer-owned proxy when the workload is production, governance-bound, enterprise, or regulated. Policy evaluation runs inside the customer account before any data is transmitted to Verify. - Use the CloudFormation or Terraform capture proxy templates when the customer environment is AWS-first and a managed deployment artifact is preferred. ## Direct vs governed integration Both deployment models are supported. The diagrams below show where capture and field retention policy evaluation happens in each one. ### Direct integration ```text Customer Backend │ ▼ Verify API ``` Used for: - Builder - Onboarding - Evaluation - Sandbox ### Governed integration ```text Customer Backend │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy │ ▼ Field Retention Policy │ ▼ Verify API ``` Used for: - Production - Governance - Enterprise - Regulated workloads > The Verify API is the same endpoint in both patterns. The customer-owned proxy is a customer-side component that evaluates capture decisions and field retention before any data is forwarded to Verify. ## Capture policy relationship The Verify API receives retained decision records. In governed deployments, two independent governance layers run inside the customer-owned proxy before any data is transmitted to Verify: - Capture decision policy — determines whether the record should be retained. Outcomes are binary: capture or skip. - Field retention policy — determines which fields are permitted to leave the customer account. Outcomes are per-field: allow, drop, redact, truncate, or neverForward. Both evaluations occur inside the customer-owned proxy before any data is transmitted to Verify. Verify receives only approved fields. > Verify does not determine what customer data is captured. The customer-owned proxy determines whether a record is retained and which fields are forwarded. Verify is not a surveillance logger — it receives only what the customer chooses to forward. For the policy contract, file shape, evaluation order, and field retention outcomes, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## First working integration path The fastest way to a working integration is a short, end-to-end loop in Sandbox before any Production rollout. Follow the steps below in order — they are designed for a first-time integrator and assume no prior Verify usage. [Try the first capture in Sandbox →](/sandbox) - Sign into the Verify Console. - Confirm your active environment is Sandbox before generating any API key. - Generate a Sandbox API key from the Verify Console. Keep it scoped to Sandbox. - Store the API key securely in a server-side secret store (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, an env-injected secret store, or equivalent). Never commit it to source control or embed it in frontend or mobile code. - Add Verify capture after your AI-assisted workflow produces an output — so the model output, prompt, and surrounding operational context can all be preserved as a retained decision record at the same point in the workflow. - Submit a retained decision record from your customer backend with the following fields: - `workflowId` — a stable identifier for the workflow that ran. - `operationalContext` — the business identifiers reviewers will use later (claimId, encounterId, transactionId, escalationId, policyId, etc.). - `model.provider` — the AI provider used by the workflow. - `model.modelId` — the model identifier used. - `aiAssistedContext` — prompt, response, or workflow context, when available. - Retrieve the record back using a known operational identifier — typically the same business identifier your reviewers would use day-to-day (for example, the claim or transaction ID). - Inspect the retained record to confirm the fields look correct — workflowId, operational context, AI-assisted context, model metadata, and timestamps. - Run verification on the record when review is needed. Verification is non-destructive and safe to repeat. - Confirm activity history in the Verify Console shows the expected capture, retrieval, and verification activity for the workflow you just integrated. - Repeat the same loop in Production only after Sandbox validation succeeds. Use a separate Production API key, separate operational dashboards, and separate downstream review surfaces per environment. ## Core concepts The Verify API is built on a small set of concepts. Once these are familiar, every endpoint and workflow on this page will feel consistent. | Concept | What it means | | --- | --- | | Retained decision record | Review-ready evidence associated with an AI-assisted workflow. | | Workflow ID | A stable name for the workflow that created the record. | | Operational context | Customer-defined identifiers used to retrieve records later. | | Retrieval key | A searchable value derived from operational context. | | Environment | Sandbox or Production workflow boundary. | | Verification status | Review-oriented state showing whether verification has occurred. | ## Authentication The Verify API uses two clearly separated authentication patterns. Use the pattern that matches the workflow. ### Capture workflows — API key Server-side capture uses an environment-scoped API key, passed as a header on each request: ```text X-Verify-Api-Key: ``` - API keys are intended for server-side capture only. - API keys are environment-aware — Sandbox keys are not valid in Production, and vice versa. - API keys should never be exposed in browsers, frontend JavaScript, mobile apps, screenshots, or logs. Treat them like database credentials. - Rotate API keys if exposure is suspected, and review records captured during the exposure window. ### Console and authenticated workflows — bearer token Authenticated user and console workflows use a bearer token passed in the standard Authorization header: ```text Authorization: Bearer ``` - Bearer tokens are used for authenticated user and console workflows. - Record retrieval, inspection, verification, API-key management, usage review, and activity review may use authenticated access. - Treat bearer tokens like any session credential — scope, expire, and protect them. ## Server-side capture pattern The Verify API is designed to be called from trusted server-side environments. The expected integration topology for capture is: ```text User or Customer Workflow → Customer Application → Customer Backend or Workflow Service → AI Workflow Produces Output → Verify Capture API ``` - The Verify API key belongs in the customer backend — read it from a secret store, not from source code. - Frontend and mobile applications should call the customer backend, not the Verify API directly. - The customer backend should attach operational context and submit the retained decision record from a trusted runtime. - Server-side submission keeps the API key, the workflow context, and the AI-assisted output co-located inside the customer's trust boundary. ## Create your first capture payload The capture payload is the customer-visible body of a retained decision record. The required and optional fields for a first integration are: | Field | Required | Purpose | | --- | --- | --- | | workflowId | Yes | Identifies the operational workflow that created the record. | | operationalContext | Yes | Provides the business identifiers reviewers will use to retrieve the record later. | | model.provider | Yes | Names the model provider used by the AI-assisted workflow. | | model.modelId | Yes | Identifies the model used by the workflow. | | aiAssistedContext | Optional | Captures prompt, response, or surrounding workflow context when available. Uses the canonical prompt/response capture model. | ### Example payload ```json { "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214" }, "model": { "provider": "anthropic", "modelId": "claude-3-5-sonnet" }, "aiAssistedContext": { "prompt": "Summarize the claim and identify escalation indicators.", "response": "Potential escalation indicators detected." } } ``` - Use stable business identifiers your operators already use day-to-day — not transient request IDs or generated tokens. - Avoid temporary test values (CLM-TEST-1, FAKE-123) in Production payloads. They make later retrieval painful. - Choose values reviewers will actually recognize later — claim, policy, encounter, transaction, escalation, or case references. ## Submit the record The illustrative request below shows the shape of a first-time capture call from a customer backend. Replace `` with the Sandbox API key generated from the Verify Console. ```bash curl -X POST "https://api.obligra.ai/api/v1/decision-records" \ -H "Content-Type: application/json" \ -H "X-Verify-Api-Key: " \ -d '{ "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214" }, "model": { "provider": "anthropic", "modelId": "claude-3-5-sonnet" }, "aiAssistedContext": { "prompt": "Summarize the claim and identify escalation indicators.", "response": "Potential escalation indicators detected." } }' ``` The host shown above is illustrative. Use the host configured for your Verify environment from the Verify Console. ## Understand the capture response A successful capture call returns a capture receipt describing the retained decision record that was just recorded. An illustrative response: ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "status": "recorded", "verificationState": "not_verified", "workflowId": "claims-review", "environment": "sandbox", "createdAt": "2026-05-18T14:30:00.000Z", "retentionUntil": "2026-05-25T14:30:00.000Z", "retrievalKeys": ["CLM-220145", "POL-99214"] } ``` ### Field meaning - **decisionRecordId** — The retained decision record identifier. Useful for direct record inspection and verification calls later. - **status** — Customer-visible state of the capture call. "recorded" indicates the record was accepted. - **verificationState** — Verification status — typically begins as "not_verified" and transitions when verification is run. - **workflowId** — Echo of the workflowId submitted at capture time. - **environment** — Confirms whether the record was captured against Sandbox or Production. - **createdAt** — ISO-8601 timestamp identifying when the record was created. - **retentionUntil** — Indicates how long the record will be retained for retrieval and review, based on the customer's retention policy. - **retrievalKeys** — Searchable values derived from operationalContext that reviewers can use to retrieve the record later. ## Retrieve a record by operational context > Verify retrieval workflows are designed around "start with what you know." > > > > > Operators retrieve retained decision records using information they already have — not internal record IDs or generated tokens. Common operational identifiers used for retrieval include: - claimId - encounterId - transactionId - escalationId - workflowId - date range An illustrative retrieval request: ```bash curl -H "Authorization: Bearer " \ "https://api.obligra.ai/api/v1/decision-records?retrievalKey=CLM-220145" ``` - Operators typically retrieve by known business identifiers — the same values they already use in their day-to-day systems. - Retrieval is environment-aware. A Sandbox retrieval call will not return Production records, and vice versa. - Wrong-environment lookups are the single most common cause of "the record is missing" reports during first integrations. Confirm the active environment before assuming the record was not captured. ## Inspect a record Inspection returns the customer-visible fields of a single retained decision record. Reviewers use inspection to confirm: - workflowId — which workflow produced the record - operational context — the business identifiers attached at capture time - AI-assisted context — the prompt, output, or workflow context preserved with the record - model metadata — the provider and model used - createdAt — when the record was created - retentionUntil — how long the record is retained for review - verificationState — current review-oriented verification status ```bash curl -H "Authorization: Bearer " \ "https://api.obligra.ai/api/v1/decision-records/dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7" ``` ## Verify a record Verification is review-oriented. It supports operational review of a retained decision record without modifying the record itself. - Verification is review-oriented — it produces a review-time signal for reviewers. - Verification is non-destructive — it does not modify the retained record. - Verification is safe to repeat — repeated calls on the same record produce consistent customer-visible state. - Verification helps support operational review across claims, compliance, quality, fraud, legal, and audit teams. ### Example request ```bash curl -X POST \ -H "Authorization: Bearer " \ "https://api.obligra.ai/api/v1/decision-records/dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7/verify" ``` ### Example response ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "verificationState": "verified", "verifiedAt": "2026-05-18T15:00:00.000Z", "resultSummary": "Record integrity was verified." } ``` ## Environments: Sandbox and Production Verify enforces strict environment separation. Sandbox and Production are independent — separate API keys, separate records, separate retrieval surfaces, separate operational dashboards. - Sandbox is intended for onboarding, testing, integration validation, and exploring retrieval workflows end-to-end. - Production is intended for live operational workflows whose retained decision records will be retrieved, reviewed, and verified by downstream teams. - API keys are environment-aware. Sandbox keys are not valid in Production, and vice versa. - Records do not move between environments. A Sandbox record cannot be retrieved from Production. - Validate the full capture-and-retrieve loop in Sandbox before promoting any workflow to Production. > Do not use Sandbox records as Production evidence. > > > > > Confirm the active environment before review, escalation, or any downstream operational action. ## Pagination Listing endpoints use cursor-based pagination. Cursors are opaque — customer code should not parse or modify them. ```json { "records": [], "count": 25, "limit": 25, "hasMore": true, "nextCursor": "opaque_cursor_value" } ``` - Treat the cursor value as opaque — its internal structure may change. - Do not parse, modify, or build cursors on the customer side. - Use nextCursor as-is to request the next page. - If a cursor is rejected as invalid, restart retrieval from the first page rather than retrying the same cursor. ## Retry and rate limits Capture and retrieval calls should be retry-aware. The customer backend is responsible for bounded retries and backoff on retry-prone paths. - Retry temporary failures with bounded retries — a small attempt count for synchronous paths, a slightly larger bound for async workers. - Apply exponential backoff with jitter between attempts to avoid synchronized retry waves. - Avoid retry storms. Unbounded retries against a degraded service make recovery harder, not faster. - Preserve operational context across retries — the same retry key, the same operationalContext, the same workflowId. - Do not create duplicate records after timeouts. If the capture status is uncertain, retrieve by operational context before resubmitting. - If retrieval shows the record was already recorded, do not retry the capture call. ### Handling 429 (rate limited or usage limit reached) - Wait before retrying — the customer backend should respect a backoff rather than retrying immediately. - Reduce concurrency on the customer side until the rate limit clears. - Validate plan and usage from the Verify Console if 429s persist beyond a transient burst. ## Error model The Verify API uses a small, customer-safe set of HTTP status codes. The table below covers the cases first-time integrators encounter most often, and the first thing to check when each one appears. | Status | Meaning | Common cause | First check | | --- | --- | --- | --- | | 400 | Bad request | Invalid or missing fields in the request body. | Check the payload structure against the documented fields. | | 401 | Unauthorized | Missing, expired, or invalid credentials. | Check the API key or bearer token for the active environment. | | 403 | Forbidden | Access, plan, scope, or environment issue. | Check role, plan, workspace, and environment alignment. | | 404 | Not found | Record or resource unavailable in the active environment. | Check the environment value first, then the identifier. | | 413 | Payload too large | Capture payload exceeds the allowed size. | Reduce payload size — keep AI-assisted context to what reviewers actually need. | | 429 | Rate limited or usage limit reached | Too many requests in a window, or plan usage limit reached. | Retry with backoff and review usage from the Verify Console. | | 500 | Unexpected server error | Temporary upstream issue. | Retry safely after a short backoff. Contact support if the condition persists. | ## Common first-time mistakes The following pitfalls are the most common operational issues new integrators encounter. Reviewing them before Sandbox rollout reduces friction during Production rollout. | Mistake | How to avoid it | | --- | --- | | Calling Verify directly from frontend code | Use a trusted backend service. Frontend and mobile applications should call the customer backend, which submits to Verify on their behalf. | | Using a Sandbox API key in Production workflows (or vice versa) | Keep environment-specific keys separate. Confirm the active environment before any capture or retrieval call. | | Missing operationalContext | Always include stable identifiers like claimId, encounterId, transactionId, or escalationId — the values reviewers will actually use to retrieve the record later. | | Using unstable workflowId values | Use meaningful, stable workflow IDs like claims-review or fraud-triage. Avoid build artifacts, generated tokens, or values that change between releases. | | Logging API keys | Redact credentials from application logs, APM systems, and error trackers before they ship to log infrastructure. | | Retrying without duplicate awareness | Preserve operational context across retries and check retrieval before resubmitting if the capture status is uncertain. | | Treating retained records as generic logs | Review retained decision records as workflow evidence — for operational, compliance, audit, quality, or legal review — not as generic application logs. | ### Record never appears Possible causes: - Wrong environment — capturing in Sandbox while searching Production (or vice versa). - Wrong API key — Sandbox key used against a Production endpoint or workspace. - Wrong tenant — capture submitted under a different tenant than the one being inspected. - Wrong workspace — capture submitted to a workspace that the reviewer is not viewing. - Capture policy skipped the record — in governed deployments, a skip rule may have matched. ### Record exists but search fails Possible causes: - Wrong operational context — searching by a value that is close to but not identical to the captured retrieval key. - Searching the wrong environment — Sandbox and Production are isolated; cross-environment retrieval will never succeed. - Retrieval key mismatch — operational context value was normalized or transformed before search. - Record indexing delay — recently captured records may take a short moment to become searchable. ### Verification fails Possible causes: - Wrong record ID — confirm the decisionRecordId belongs to the active environment. - Wrong environment — verifying a Sandbox record against a Production credential, or vice versa. - Temporary service issue — retry verification with a short backoff before escalating. ### Capture policy unexpectedly skipping records Specific to governed deployments using a customer-owned proxy. Possible causes: - Skip rule matched — review the proxy logs to see which rule fired. - Required field missing — the canonical capture model requires workflowId, environment, operationalContext, model.provider, model.modelId, prompt, and response. - defaultAction is set to skip — outputs that do not match an explicit capture rule are skipped. - Invalid policy file — the proxy fails closed when the policy file is missing or malformed. - Policy not loaded — confirm the proxy loaded the latest policy at startup. ### 401 / 403 authentication issues Possible causes: - Revoked key — the API key was revoked from the Verify Console. - Wrong environment key — Sandbox keys are not valid in Production, and vice versa. - Expired bearer token — refresh authentication before retrying retrieval, inspection, or verification calls. - Workspace mismatch — the credential is scoped to a different workspace than the request targets. For deeper coverage organized by symptom, see [Troubleshooting Verify Integrations](/resources/troubleshooting-verify-integrations) . ## How to know it's working Use this checklist to confirm a first integration is wired end-to-end. If every item below is true, the integration is working correctly and is ready to move on to a Production readiness review. - Generate API key — a Sandbox API key has been generated from the Verify Console and stored server-side. - Create decision record — the customer backend submits a capture call that returns HTTP 200 with status: recorded. - Receive decisionRecordId — the capture response includes a decisionRecordId in the dr_ format. - Retrieve record — calling retrieval with the same operational context that was captured returns the record. - Open record in Verify Console — the record is visible in the Verify Console with workflowId, operational context, prompt, response, and model metadata populated. - Verify record — calling verification on the captured record returns a verification result. - Confirm activity history — the Verify Console activity feed shows capture, retrieval, and verification events for the workflow. - Confirm retrieval works by operational context — the record can be found by a business identifier a reviewer would already know (claimId, encounterId, transactionId, escalationId, ticketId). > If all checks pass, the integration is working correctly. Move on to the Production readiness checklist below before Production rollout. ## Production readiness checklist Before promoting a workflow from Sandbox to Production, the following should all be true. This checklist closes the common gaps customer teams discover late. - Sandbox capture succeeds — a retained decision record is recorded from the customer backend. - The record can be retrieved by operational context using the same identifiers reviewers will use day-to-day. - The record can be inspected — workflowId, operational context, AI-assisted context, model metadata, and timestamps all look correct. - Verification workflow works end-to-end — calling verification on a captured record returns a verification result. - API keys are stored server-side in a secret store — not in source control, frontend bundles, or mobile binaries. - Retry behavior is bounded, backoff-aware, and idempotent — duplicate records are prevented across retries. - Rate-limit handling exists — 429 responses trigger backoff and concurrency reduction rather than immediate retries. - Operational identifiers are stable — workflowId and operationalContext values reviewers will actually recognize. - Sandbox and Production credentials are separated — distinct API keys, distinct downstream review surfaces, distinct operational dashboards. - A support and runbook process is defined — who responds when capture or retrieval starts failing, and how the customer team escalates. ## Related documentation Pair this reference with the following resources for the full first-integration picture: - [Verify SDK Reference — capture SDK methods, environment-aware onboarding, and operational context guidance.](/resources/verify-sdk-reference) - [Configuring an AI Capture Policy — capture decision policy and field retention policy for customer-owned proxy deployments.](/resources/configuring-an-ai-capture-policy) - [Troubleshooting Verify Integrations — failure modes organized by symptom across authentication, capture, retrieval, verification, capture policy, SDK, and deployment.](/resources/troubleshooting-verify-integrations) - [Webhook Events — server-to-server notifications about selected retained decision record activity.](/resources/webhooks) - [Quickstart — first-time setup and environment readiness for new customer teams.](/resources/quickstart) - [Customer Security Overview — broader customer-side security posture around Verify integrations.](/resources/security-overview) - [Using AI Assistants with Verify — how AI-assisted workflows fit alongside Verify capture.](/resources/using-ai-assistants-with-verify) - [Reference Architecture: AWS — customer-side reference deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) - [What Is Obligra Verify — product positioning and capabilities overview.](/resources/what-is-verify) - [Why AI Decisions Need a System of Record — the operational thesis behind retained decision records.](/resources/why-ai-decisions-need-system-of-record) --- --- title: AWS Lambda Integration Pattern slug: aws-lambda-integration-pattern category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/aws-lambda-integration-pattern canonicalUrl: "https://obligra.ai/resources/aws-lambda-integration-pattern" llmTags: - llm-aligned - architecture-core - integration - retrieval-tier-3 - supporting-reference --- # AWS Lambda Integration Pattern _Architecture_ _Many AI-assisted workflows in customer environments run on AWS Lambda — event-driven triggers, scheduled jobs, post-processing steps, stateless API handlers — and Verify capture from Lambda is well-trodden ground. The pattern itself is unsurprising once the Lambda execution model is taken into account: the function lives in the customer’s AWS account, reads the Verify API key from a customer secret store at cold start, caches it for the warm lifetime of the function, attaches stable operational context to every capture call, bounds its retries inside the function timeout, and stays environment-aware end-to-end. In practice, the same customer-side discipline applied to any other outbound HTTPS call from Lambda transfers here without modification._ ## Overview AWS Lambda is one of the most common runtimes customer teams choose for AI-assisted workflows — event-driven triggers, scheduled jobs, post-processing steps, and stateless API handlers all run cleanly on it, and most organizations already operate Lambda functions adjacent to the workflows they want to capture. Verify integrates from Lambda the same way it integrates from any trusted server-side runtime: HTTPS to the public API surface, environment-scoped credentials, stable operational context attached at capture time. The pattern below is the canonical shape customer teams converge on after their first integration. The Lambda function sits in the customer’s AWS account. Verify’s public API is the boundary. Everything between the two — IAM, secret resolution, retry handling, observability — is customer-side architecture, which is what allows customer teams to apply their existing Lambda tooling without modification. > Lambda capture is a customer-side pattern. The function lives in the customer’s AWS account. > > > > > Verify does not provide a customer-side Lambda. Customer teams adopt the pattern using their existing Lambda tooling, IAM model, and deployment system. ## Why this matters Lambda has operational constraints — function timeout, cold start latency, per-invocation isolation, and stateless-by-design execution — that shape how Verify integration must behave inside the function boundary. Getting those constraints right is the difference between a clean Lambda integration and one that fights the runtime. - Function timeout bounds the retry budget. Unbounded retries inside Lambda truncate when the function dies — turning recoverable transient failures into permanent capture gaps. - Cold starts amplify secret retrieval cost. A function that re-reads the secret from the secret manager on every invocation pays cold-start latency repeatedly and adds load on the secret manager. - Stateless invocations lose retry state. The customer team cannot rely on in-process retry state across invocations; idempotency must live in the queue, the retry key, or the operational context. - Environment configuration must be explicit. Lambda environment variables tie credentials to the function; mixing Sandbox and Production functions in one stack is a common source of cross-environment capture. - Function logs ship to long-term storage. Anything emitted from the function — including stack traces with embedded arguments — lands in customer log infrastructure with the customer's retention policy. ## Recommended pattern The recommended customer-side Lambda capture pattern reads the API key from a customer secret store at cold start, caches it for the function’s warm lifetime, attaches stable operational context at capture time, and bounds retries inside the function timeout. ### Cold-start initialization - Resolve the active environment (Sandbox or Production) from a customer-controlled configuration source. - Read the environment-scoped Verify API key from the customer's secret manager (AWS Secrets Manager, Parameter Store, or equivalent). - Cache both values in module-level state outside the handler function so warm invocations reuse them without re-reading. - Initialize the HTTP client once at module scope so warm invocations reuse the connection pool. - Fail fast if the environment is ambiguous or the credential cannot be retrieved — do not silently fall back. ### Per-invocation handler - Receive the trigger event (API Gateway, EventBridge, SQS, direct invoke, or scheduled job). - Run the AI-assisted workflow step that produces the output to be preserved. - Assemble the capture payload — workflowId, operationalContext, AI-assisted context, and any non-sensitive model metadata. - Submit to the Verify Capture API over HTTPS using the cached API key. - Apply bounded retries with exponential backoff and jitter, fitted inside the function's remaining budget. Use a stable retry key so duplicate capture is detectable by retrieval-by-context. - Emit a customer-side log line with environment, workflowId, operational identifier reference, outcome class, retry count, and (if returned) decisionRecordId. Never log the credential value. ## Architecture diagram The diagram below is a customer-safe view of Lambda capture. Every box on the left is customer-owned and sits in the customer’s AWS account; the Verify Capture API is the only external boundary. ```text Customer-owned (customer AWS account) Verify (public boundary) ───────────────────────────────────── ───────────────────────── Trigger ├─ API Gateway ├─ EventBridge ├─ SQS / customer queue ├─ Direct invoke └─ Scheduled (EventBridge rule) │ ▼ Lambda Function ──────── (cold start) ────▶ Customer Secrets Store │ (Secrets Manager / │ Parameter Store / etc.) │ │ │ ◀───── env-scoped API key (cached) ────────┘ │ │ (per invocation) ├─ Run AI-assisted workflow step ├─ Assemble capture payload │ workflowId │ operationalContext │ AI-assisted context │ │ (HTTPS, X-Verify-Api-Key, bounded retries) └────────────────────────────────────────▶ Verify Capture API │ ▼ Retained Decision Record Customer log stream (CloudWatch / customer log infra) ├─ Outcome class, retry count, env, workflowId └─ decisionRecordId (when returned) ``` ## How it works Lambda capture is shaped by the function lifecycle — initialization at cold start, fast execution per invocation, and warm reuse across invocations from the same execution environment. ### Initialization at cold start The first invocation in a fresh execution environment runs module-level code before the handler. This is where the active environment is resolved, the API key is read from the secret manager, and the HTTP client is initialized. Every subsequent warm invocation reuses these values without paying the same cost. ### Handler execution The handler runs the AI-assisted workflow step, assembles the capture payload, and submits to Verify. The function treats the cached API key as a process-scoped secret — never logged, never serialized into structured logs, never included in stack traces. ### Retry behavior Retries are bounded by the function timeout. The customer runtime should track its remaining budget and stop retrying well before the function dies — preferring to surface a retryable failure to the Lambda retry policy (or to a DLQ) rather than to truncate mid-retry. A stable retry key carried through every attempt preserves the retrieval-by-context deduplication path. ### Environment-aware routing The active environment is resolved explicitly from configuration — not inferred from the function name. The function should refuse to capture when the environment is ambiguous, and Sandbox functions should never read Production credentials regardless of how the deployment system wires them. ## Customer responsibilities The customer team owns the Lambda function, its IAM, its configuration, its deployment, and its observability. Verify owns the public API. The boundary between the two is the HTTPS call. - Provision distinct Lambda functions or distinct configurations per environment — Sandbox and Production functions never share credentials. - Grant the function the minimum IAM permissions required to read the customer secret store and emit logs. Apply the customer's existing IAM review process. - Read the API key from a customer secret store at cold start, cache it at module scope, never read from disk or source. - Resolve the active environment from explicit configuration at cold start. Fail fast on missing or ambiguous environment. - Bound retries inside the function timeout. Track remaining budget and stop retrying before truncation. - Use a stable retry key across attempts for the same business event so duplicate-capture is detectable by retrieval-by-context. - Emit customer-side observability — outcome class, retry count, environment, workflowId, operational identifier reference, decisionRecordId — without ever logging the API key value. - Apply the customer's existing Lambda deployment discipline — staged rollout, alarms, canary, and rollback runbooks. ## Common mistakes The pitfalls below are the most common Lambda integration mistakes customer teams encounter. Each one is recoverable, but each one costs avoidable rework before Production rollout. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | API key hardcoded in Lambda environment variables in code | Environment variables baked into source or committed to the deployment manifest persist in source control and propagate to every clone. | Inject the env var from a customer secret store at deploy time, or read from the secret manager at cold start. | | Reading the secret on every invocation | Adds latency, adds load on the secret manager, and provides no security benefit over reading once at cold start. | Read at module scope (cold start), cache for the warm lifetime, re-read only when rotation requires it. | | Unbounded retries inside the function | Function timeout truncates the retry mid-attempt, leaving capture status uncertain and the next invocation unable to resume. | Bound retries inside the function timeout. Surface retryable failure to the Lambda retry policy, queue, or DLQ for the next attempt. | | Sharing a function across Sandbox and Production | Cross-environment capture happens silently when configuration drift makes the function read the wrong credential. | Distinct functions or distinct configurations per environment. Resolve the active environment explicitly at cold start. | | Losing operational context across the invocation boundary | Functions triggered from queue messages that omit operationalContext cannot reconstruct it from the trigger alone. | Serialize workflowId and operationalContext into the trigger event itself. Treat the event shape as a contract. | | Logging the API key for debugging during integration | Log lines from Lambda ship to CloudWatch and downstream log infrastructure where retention and access are different from the function runtime. | Log a non-reversible key reference ("prod-v3") when correlation is needed. Never log the credential value. | | Treating cold-start latency as a Verify problem | Cold-start latency is a customer-side runtime cost, not a Verify integration cost. Treating it as a Verify issue misroutes investigations. | Measure and report cold-start initialization separately from per-invocation capture latency in customer-side observability. | ## Validation checklist Before promoting a Lambda-based Verify integration from Sandbox to Production, the following customer-side controls should all be in place. - Distinct Lambda functions or distinct configurations per environment — Sandbox and Production never share credentials. - API key is read from a customer secret store at cold start, cached at module scope, never present in source control. - Active environment is resolved explicitly at cold start; the function fails fast on missing or ambiguous environment. - Retries are bounded inside the function timeout with exponential backoff and jitter, and carry a stable retry key. - Operational context (workflowId plus stable business identifiers) is assembled from the trigger and attached at capture time. - Customer-side observability captures outcome class, retry count, environment, workflowId, operational identifier reference, and decisionRecordId — and excludes the API key value. - Customer-side deployment discipline applies — staged rollout, alarms, canary, and a rollback runbook. - Cold-start initialization and per-invocation capture latency are reported separately in customer-side observability. - A Sandbox dry-run from the actual Production trigger shape has been performed — capture, retrieval-by-context, and verification all succeed. ## Related documentation Pair this guide with the following resources for the full Lambda integration picture: - [Server-Side Capture Pattern — trusted server-side topology Lambda capture sits inside.](/resources/server-side-capture-pattern) - [API Key Placement and Secret Storage — credential discipline for Lambda cold-start retrieval.](/resources/api-key-placement-and-secret-storage) - [Environment Strategy — Sandbox vs Production discipline across Lambda environments.](/resources/environment-strategy) - [Operational Context Mapping — retrieval keys attached at capture time inside the handler.](/resources/operational-context-mapping) - [Reference Architecture: AWS — customer-side AWS topology that contains Lambda integrations.](/resources/reference-architecture-aws) - [Queue-Based Capture Pattern — pairs naturally with queue-fed Lambda consumers.](/resources/queue-based-capture-pattern) - [Customer Integration Patterns — architecture hub covering Lambda alongside other patterns.](/resources/customer-integration-patterns) --- --- title: Compliance approach slug: compliance-approach category: Trust & Security retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/compliance-approach canonicalUrl: "https://obligra.ai/resources/compliance-approach" llmTags: - llm-aligned - trust-security - retrieval-tier-3 - supporting-reference --- # Compliance approach _Trust & Security_ _Verify is not a compliance program, and it does not produce compliance posture by itself. The customer team continues to own audit, compliance, legal, and risk programs the same way it does for every other system in the customer environment. What Verify changes is the evidence layer underneath those programs: retained decision records for AI-assisted workflows that reviewers can retrieve months later by operational context and verify against the original capture moment. The compliance approach is intentionally narrow — Verify supports customer-owned compliance programs, it does not replace them._ ## Overview Compliance for AI-assisted operational workflows is not the same problem as compliance for traditional deterministic software. Organizations rolling AI-assisted decision-making into regulated workflows consistently discover that review obligations look familiar — audit sampling, policy review, regulatory inquiry, escalation review — but operate over decisions whose context is harder to reconstruct after the fact. The compliance value of Verify is practical: when a workflow is questioned later, reviewers retrieve the retained decision record by operational context and inspect it directly, instead of reconstructing the event from logs, screenshots, tickets, and provider history. The architectural boundary remains clear and is intentional. Verify supports the customer’s compliance program by preserving review-ready records. Policies, controls, regulatory interpretation, audit planning, and review outcomes remain with the customer team. In practice, that separation is what allows enterprise compliance programs to adopt Verify without reshaping the program around it. ## Why this matters for GenAI workflows GenAI workflows produce decisions whose review demand is high and whose reconstruction cost is also high — and three concrete properties of those workflows are what drive both costs. Each property is load-bearing on its own, and together they make the case for a retained-record layer rather than a reconstruction-from-logs program. ### Decisions are individual Compliance, audit, fraud, legal, and operations reviewers look at one decision at a time. They arrive with a claim, an encounter, a transaction, an escalation, or a case reference — not an aggregate of workflow behavior. Retained decision records are the artifact that supports single-decision review. ### Reconstruction is brittle Re-running the AI-assisted workflow after the fact often produces a different result because the model, prompts, retrieved data, or surrounding workflow have moved on. In practice, reconstruction cannot be the foundation of review for AI-assisted decisions; preservation can. ### Evidence demands compound As AI-assisted workflows scale, the number of decisions subject to review grows quickly. Each periodic audit, each regulatory inquiry, each escalated case adds to the evidence demand. A retained, retrievable record per decision is the practical answer, and the tradeoff is straightforward: the cost of preserving records is paid once at capture, while the cost of reconstruction is paid every time review happens. ## Verify's role Verify’s role inside a compliance program is to preserve review-ready evidence and support later retrieval. It is one component of a broader governance picture — not a substitute for the program itself. - Preserve retained decision records produced by AI-assisted workflows that customer teams choose to capture. - Support retrieval of those records using the same operational identifiers the customer team uses operationally (claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId, and similar). - Expose customer-visible verification status that supports review-oriented confidence in the retained record. - Surface review workflows through the Verify Console for customers whose compliance, audit, legal, and risk teams need to inspect retained records. - Operate as a customer-side architectural component — installed inside the customer's broader compliance and governance environment, not replacing it. ## Customer responsibility Compliance posture is determined by the customer’s policies, controls, regulatory environment, audit program, and review process. Each of these continues to be a customer-owned program. Verify supports the review surface that program operates over. ### Policies and controls The customer team defines the policies that govern AI-assisted workflows — which workflows are in scope, what review is required, what outcomes are acceptable, and what remediation applies when expectations are not met. Controls (preventive, detective, corrective) are customer-defined and customer-operated. ### Regulatory interpretation The customer team’s legal and compliance functions determine how regulatory requirements apply to the AI-assisted workflows in scope. Verify’s role is to support evidence retrieval — not to interpret regulation on the customer’s behalf. ### Audit planning and execution Audit scope, sampling methodology, frequency, and review standards are determined by the customer’s audit program. Verify supports retrieval and inspection during audit execution; the program itself remains a customer-side discipline. ### Review outcomes The outcome of any compliance, audit, legal, or risk review — whether a record is acceptable, requires remediation, or triggers escalation — is determined by the customer team’s review process. Verify provides the artifact; the customer team decides the outcome. ## How Verify supports compliance needs The table below summarizes the compliance needs Verify supports and the customer-side responsibility that pairs with each. Together they form a coherent compliance picture for AI-assisted workflows. | Compliance need | Verify support | Customer responsibility | | --- | --- | --- | | Evidence retrieval | Preserves retained decision records and supports retrieval by operational context. | Define the review process — when retrieval is needed, who performs it, what is required to be inspected. | | Audit review | Supports retrieval and inspection of retained records, with customer-visible verification status. | Determine audit scope, sampling methodology, frequency, and standards. | | Operational accountability | Connects retained records to the operational context the customer team attached at capture time. | Maintain workflow ownership; ensure operational context aligns with the customer team's authoritative systems. | | Workflow documentation | Preserves the AI-assisted context that the customer team chose to submit for each workflow event. | Document policies, procedures, and workflow design inside the customer's broader governance program. | | Exception review | Supports retrieval and review of disputed, escalated, or anomalous AI-assisted decisions. | Decide outcome, remediation, escalation path, and any downstream operational actions. | | Retention planning | Supports retained record workflows under the customer's active service contract. | Determine regulatory retention requirements, contractual obligations, and customer-side retention policy. | | Access control | Supports controlled access patterns to retained records through configured customer access. | Manage users, roles, and permissions inside the customer's identity and access program. | ## How Verify fits into broader governance The layered view below summarizes how Verify fits into a broader customer governance program. Verify is one layer in a larger picture — the program itself remains a customer-owned discipline. ```text ╔══════════════════════════════════════════════════════════════════╗ ║ ║ ║ Policies and Governance ║ ║ ───────────────────── ║ ║ Customer-owned: AI-use policies, control framework, ║ ║ regulatory interpretation, risk appetite, retention ║ ║ policy. ║ ║ ║ ║ ────────────────────────────────────────────────────────── ║ ║ ║ ║ Review and Audit Processes ║ ║ ────────────────────── ║ ║ Customer-owned: audit planning, sampling, periodic ║ ║ review, escalation, legal review, risk review. ║ ║ ║ ║ ────────────────────────────────────────────────────────── ║ ║ ║ ║ Operational Workflows ║ ║ ────────────────── ║ ║ Customer-owned: business workflows that produce ║ ║ AI-assisted decisions — claims, encounters, ║ ║ transactions, escalations, cases. ║ ║ ║ ║ ────────────────────────────────────────────────────────── ║ ║ ║ ║ Verify Retained Decision Records ◀── role ║ ║ ────────────────────────────── ║ ║ Verify: preserves the records produced by ║ ║ AI-assisted workflows the customer chooses to ║ ║ capture, and supports later retrieval, review, and ║ ║ verification. ║ ║ ║ ║ ────────────────────────────────────────────────────────── ║ ║ ║ ║ AI-assisted Systems ║ ║ ───────────────── ║ ║ Customer-owned: model providers, prompts, runtimes, ║ ║ and the AI-assisted workflow code itself. ║ ║ ║ ╚══════════════════════════════════════════════════════════════════╝ Verify supports governance. Verify is not governance itself. ``` Every layer except the retained record layer is customer-owned. Verify’s role is to preserve the records produced by AI-assisted workflows the customer chooses to capture — making the layers above reviewable when audit, compliance, legal, or risk programs need them. ## Compliance considerations The considerations below summarize how customer compliance programs should think about Verify during integration planning and ongoing operation. None of them displace the customer’s existing program — they integrate with it. - Treat Verify as a customer-side architectural component, installed inside the customer's broader governance environment. Compliance posture remains shaped by the customer team's policies and controls. - Align the AI-assisted workflows that produce retained records with the customer's existing scope decisions — which workflows are subject to review, sampling, or escalation. - Confirm residency and retention against the customer's active service contract and the customer team's regulatory environment, during integration planning rather than after Production rollout. - Document the customer-side responsibilities described above — review process, audit standards, exception handling, retention policy — inside the customer's governance documentation. - Integrate retrieval-by-operational-context into the customer's existing audit and review workflows. The retrieval keys reviewers use should match the business identifiers the customer team already uses operationally. - Treat verification status as a review-oriented input. It supports confidence in the retained record; the customer's review process determines outcomes. ## Common misconceptions The misconceptions below are common during compliance review of an AI-assisted workflow that uses Verify. Each clarifies a boundary that the broader model implies but is worth surfacing explicitly. | Misconception | How to think about it | | --- | --- | | Adopting Verify makes the organization compliant. | Verify preserves review-ready records. Compliance posture is determined by the customer's policies, controls, regulatory environment, and audit program — all of which remain customer-owned. | | Verify produces audit attestations or regulatory certifications. | Verify supports compliance review by preserving retained decision records. Specific certifications applicable to the platform are described in the active published service description. | | Verify replaces the customer's audit or compliance review program. | Verify is one component of a broader governance program. Audit and compliance review continue to be customer-owned disciplines. | | Verification status is a compliance determination. | Verification status is a customer-visible record-level signal. Compliance determinations are made by the customer team's review process. | | Verify retains everything that could ever be useful for audit. | Verify retains what the customer team chooses to submit. Authoritative customer systems remain the source of truth for operational state. | | Verify automates exception remediation. | Verify supports retrieval and review of exceptions. The customer team decides outcomes and operates the remediation workflows. | | Retained records can be moved between Sandbox and Production for testing audit scenarios. | Sandbox is for validation. Production is the operational record. Records do not move between environments — Sandbox records are not Production evidence. | ## Related documentation Pair this overview with the following pages for the full compliance and governance picture: - [Security overview — Shared Responsibility Model and the broader security posture.](/resources/security-overview) - [Data handling and residency — customer submission discipline and residency considerations.](/resources/data-handling) - [Record integrity and verification — customer-visible verification model for retained records.](/resources/record-integrity-and-verification) - [Verification lifecycle — the five-stage trust progression compliance reviewers use to judge retained records.](/resources/verification-lifecycle) - [Audit Readiness for AI Workflows — what auditors look for and how retained decision records answer the recurring questions.](/resources/audit-readiness-ai-workflows) - [Evidence vs logs — why retained decision records are a different surface from application logs.](/resources/evidence-vs-logs) - [Operational context mapping — how customers choose identifiers reviewers will use later.](/resources/operational-context-mapping) - [Environment Strategy — Sandbox vs Production discipline across compliance review.](/resources/environment-strategy) --- --- title: Configuring an AI Capture Policy slug: configuring-an-ai-capture-policy category: Developers retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/configuring-an-ai-capture-policy canonicalUrl: "https://obligra.ai/resources/configuring-an-ai-capture-policy" llmTags: - llm-aligned - integration - capture-policy - selective-retention - implementation-guide - retrieval-tier-3 - supporting-reference --- # Configuring an AI Capture Policy _Developers_ _The AI Capture Policy is a customer-side governance artifact that runs inside the Customer-Owned Proxy and decides two things before any record reaches Verify: whether an interaction becomes a retained decision record at all, and which fields are permitted to leave the customer environment when it does. The policy is yours to define, version, and operate — Verify receives only the records your proxy chooses to forward, and only the fields your proxy chooses to forward with them. In practice, organizations that treat the policy as a versioned governance file rather than as application configuration consistently report lower audit friction and clearer review trails. This page covers the two-layer policy model (capture decisions and field retention), the three capture modes (forward_all · intent_only · policy), the rule evaluation order, worked examples across fraud, clinical, and claims workflows, proxy configuration, local testing, logging discipline, and recommended policy design._ ## Executive overview An AI capture policy controls which outputs from your AI-assisted workflows become retained decision records in Verify. The policy lives in a JSON file you own and version, loaded by the customer-owned capture proxy at startup. The proxy evaluates the policy locally — Verify only receives the records your proxy chooses to forward. Verify is not intended to log every model call your application makes. Most AI-assisted workflows produce a mix of decision-worthy outputs and operational noise — drafts, retries, playground experiments, no-action responses. A well-designed capture policy preserves the outputs that matter for later review, retrieval, and accountability, and skips the rest. > Retain the records that matter later. Skip everything else. > > > > > The capture policy is your control plane for selective retention. The proxy evaluates the rules locally. Verify receives only what you choose to forward. > Verify does not decide what your organization must capture. The customer-owned proxy evaluates the local capture policy and forwards only the retained decision records your organization chooses to retain. ## Why capture policy matters Retained decision records should be outputs that are useful for later review and retrieval, verification-oriented review of decision integrity, audit workflows and operational accountability, and review-ready evidence. Outputs that typically should not be captured — drafts, intermediate rewrites, playground or test prompts, low-value summaries, duplicate retries, and no-action responses where no recommendation was made — add noise without supporting review. A well-designed capture policy helps your retained decision records stay meaningful and retrievable. Reviewers arriving later — compliance, audit, fraud, clinical, or operations — should find retained decision records that match the workflows they actually need to inspect, not a haystack of every model invocation. ## How the capture policy works The capture policy is evaluated entirely by the customer-owned proxy before any request reaches Verify. The flow is straightforward: - The proxy loads your policy file at startup. If the file is missing or invalid, the proxy fails closed and rejects requests until a valid policy is provided. - For each incoming request, the proxy evaluates the policy rules locally — no external lookup, no callback to Verify. - If the policy decides to capture, the request is forwarded to Verify as a retained decision record. - If the policy decides to skip, the request is not sent to Verify. A local response is returned to the caller indicating which rule matched and why. - Verify does not enforce, override, or audit your capture policy. The policy file is yours to define, modify, and version. ## Capture decisions vs field retention A capture policy answers two separate questions: - Should this workflow output become a retained decision record? - If retained, which fields are permitted to leave the customer account? The first question is answered by the **Capture Decision Policy**. It decides whether a workflow output is forwarded to Verify at all. Outcomes are binary — `capture` or `skip` — and are driven by `captureIntent`, `workflowType`, `riskLevel`, `environment`, `captureRules`, and `skipRules`. The second question is answered by the **Field Retention Policy**. It decides which prompts, responses, operational context fields, metadata fields, and identifiers may be forwarded with a retained record. Outcomes are per-field — `allow`, `drop`, `redact`, `truncate`, or `neverForward`. Both evaluations occur inside the customer-owned proxy, inside the customer's AWS account, before any data is transmitted to Verify. The two layers are independent — a record may be retained while specific fields are redacted, truncated, or removed entirely. ### Two-layer evaluation flow ```text Customer Application │ ▼ Customer-Owned Proxy │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 1. Capture Decision Policy │ │ Evaluate skipRules and captureRules. │ │ Outcome: skip → request not sent to Verify. Stop. │ │ capture → continue. │ └─────────────────────────────────────────────────────────────┘ │ capture ▼ ┌─────────────────────────────────────────────────────────────┐ │ 2. Field Retention Policy │ │ For each field in the payload, apply: │ │ allow → field is forwarded as-is │ │ drop → field is removed from the payload │ │ redact → field value is masked before forward │ │ truncate → field value is shortened before forward │ │ neverForward → field is permanently excluded │ └─────────────────────────────────────────────────────────────┘ │ ▼ Approved Fields Only │ ▼ Verify API │ ▼ Decision Record │ ▼ Verify Console │ ▼ Verification & Evidence ``` > Verify does not determine what customer data is captured. The customer-owned capture policy determines what information is eligible to become a retained decision record. Policy evaluation occurs inside the customer's AWS account before any data is transmitted to Verify. Verify receives only the approved fields forwarded by the customer-owned proxy. ### Independent controls Capture decisions and field retention are independent controls. A record may be retained while certain fields are redacted, truncated, or removed entirely. Common combinations: - Retain workflow metadata — workflowType, riskLevel, environment, and operational identifiers are forwarded as-is. - Retain the recommendation — the model's output text is allowed so reviewers can inspect what was generated. - Drop tokens — bearer tokens, API keys, and session credentials are removed before forward. - Drop internal notes — operator scratchpads, debug traces, and internal comments are removed before forward. - Redact identifiers — personally identifiable identifiers are masked so retrieval keys remain stable but raw values do not leave the customer account. - Truncate large responses — long model outputs are shortened to a bounded length to keep retained records review-sized. ## Field retention example The example below illustrates a typical field retention outcome for a support-workflow payload. Capture has already been decided — this is the second layer running against the fields in the payload. ### Input payload - ticketId - customerId - severity - environment - prompt - response - authToken - customerSSN - internalNotes - debugTrace - rawPayload ### Policy result | Field | Decision | Reason | | --- | --- | --- | | ticketId | Forwarded | Retrieval key — supports later review by case. | | customerId | Forwarded | Operational identifier — supports retrieval by business context. | | severity | Forwarded | Operational metadata — describes the workflow. | | environment | Forwarded | Operational metadata — distinguishes production from non-production review. | | prompt | Forwarded | Decision input — needed to understand what the model was asked. | | response | Forwarded | Decision output — needed to understand what the model produced. | | authToken | Dropped | Credential — must not leave the customer account. | | customerSSN | Dropped | Sensitive identifier — not required for review. | | internalNotes | Dropped | Internal commentary — not part of the retained decision. | | debugTrace | Dropped | Diagnostic data — operationally noisy and not review-ready. | | rawPayload | Dropped | Unfiltered upstream payload — superseded by the approved fields above. | > Dropped fields never reach the Verify API, the retained decision record, the Verify Console, or evidence reports. They are removed by the customer-owned proxy before any data leaves the customer account. ## Capture modes The proxy supports three capture modes. Pick the mode that matches how your application already decides whether an output is decision-worthy. | Mode | What it captures | When to use it | Tradeoff | | --- | --- | --- | --- | | forward_all | Every valid request received by the proxy is forwarded to Verify as a retained decision record. | Your upstream workflow already filters out low-value outputs, drafts, playground prompts, duplicate retries, and non-reviewable responses before sending the request to the proxy. | If the upstream does not pre-filter, this mode captures everything — including noise. Most enterprise rollouts move to policy mode quickly for that reason. | | intent_only | Only requests where captureIntent is explicitly true are forwarded. All other requests are skipped. | Your application logic decides capture intent before sending the request to the proxy. | Rule logic moves into your application. The proxy does not evaluate skip or capture rules. | | policy | The proxy evaluates skipRules and captureRules from your JSON policy file. | Capture decisions should be based on workflow type, risk level, recommended action, capture reason, or other operational context. | Most flexible. Requires a maintained policy file. Skip rules always take priority. | ## Example capture policy The policy file below illustrates the canonical shape — mode, defaultAction, requiredFields, skipRules, captureRules, and reasonCodes. All values are illustrative; field names and conditions are part of the policy contract. ```json { "mode": "policy", "defaultAction": "skip", "requiredFields": ["workflowType", "riskLevel"], "skipRules": [ { "name": "skip_test_prompts", "field": "environment", "condition": "in", "values": ["test", "playground", "sandbox"], "reason": "Test and playground outputs are not retained" }, { "name": "skip_drafts", "field": "workflowType", "condition": "equals", "value": "draft", "reason": "Drafts are not decision-worthy" }, { "name": "skip_no_action", "field": "recommendedAction", "condition": "equals", "value": "none", "reason": "No-action outputs do not require retention" } ], "captureRules": [ { "name": "capture_high_risk", "field": "riskLevel", "condition": "in", "values": ["high", "critical"], "reason": "High-risk decisions require retained records" }, { "name": "capture_clinical_review", "field": "workflowType", "condition": "equals", "value": "clinical_review", "reason": "Clinical review recommendations are decision-worthy" }, { "name": "capture_claims_decision", "field": "workflowType", "condition": "equals", "value": "claims_decision", "reason": "Insurance claims decisions require accountability" } ], "reasonCodes": { "skip_test_prompts": "NOT_PRODUCTION", "skip_drafts": "DRAFT_OUTPUT", "skip_no_action": "NO_DECISION", "capture_high_risk": "HIGH_RISK_DECISION", "capture_clinical_review": "CLINICAL_ACCOUNTABILITY", "capture_claims_decision": "CLAIMS_ACCOUNTABILITY" } } ``` ## Rule evaluation order When the proxy receives a request in policy mode, evaluation follows a fixed sequence. Skip rules take priority over capture rules so that explicitly excluded categories (drafts, retries, test environments) are never accidentally captured. ```text Incoming request │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 1. Validate required fields │ │ If any field in requiredFields is missing, │ │ reject with an error. Stop. │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 2. Evaluate skip rules in order │ │ First matching skip rule wins. │ │ If matched → skip locally. Stop. │ └─────────────────────────────────────────────────────────────┘ │ no skip rule matched ▼ ┌─────────────────────────────────────────────────────────────┐ │ 3. Evaluate capture rules in order │ │ First matching capture rule wins. │ │ If matched → forward to Verify. Stop. │ └─────────────────────────────────────────────────────────────┘ │ no capture rule matched ▼ ┌─────────────────────────────────────────────────────────────┐ │ 4. Apply defaultAction │ │ "skip" → request not sent to Verify │ │ "capture" → request forwarded to Verify │ └─────────────────────────────────────────────────────────────┘ ``` > Skip rules take priority because low-value or unsafe records should be excluded before evaluation continues — even when a capture rule would also match. Order your skip rules from most specific to most general. ## Common policy fields These are fields your application includes in the request payload sent to the proxy. You control which fields are present and what values they carry — the proxy reads them as inputs to the policy. | Field | Description | Example values | | --- | --- | --- | | workflowType | The type of AI-assisted workflow that produced the output. | clinical_review, claims_decision, fraud_review, draft | | riskLevel | Risk classification of the output, set by your application. | low, medium, high, critical | | environment | Deployment environment the request originated from. | production, staging, test, playground | | recommendedAction | The action recommended by the model in this workflow. | approve, escalate, deny, none | | captureReason | Why this output should be retained, if your application sets it. | regulatory_requirement, high_value_decision | | captureIntent | Explicit capture intent flag (only consulted in intent_only mode). | true, false | | operationalContext.* | Nested operational metadata accessible via dotted-path lookups. | operationalContext.department, operationalContext.region | ## Safe examples Worked examples below. Each is a single rule body — drop it into the matching skipRules or captureRules array in your policy file. ### Capture rules Capture high-risk fraud review ```json { "name": "capture_fraud_high_risk", "field": "workflowType", "condition": "equals", "value": "fraud_review", "reason": "Fraud review outputs require retained accountability" } ``` Capture clinical review recommendation ```json { "name": "capture_clinical", "field": "workflowType", "condition": "equals", "value": "clinical_review", "reason": "Clinical recommendations are decision-worthy" } ``` Capture insurance claims decision ```json { "name": "capture_claims", "field": "workflowType", "condition": "equals", "value": "claims_decision", "reason": "Claims decisions require audit trail" } ``` ### Skip rules Skip playground / test prompts ```json { "name": "skip_non_production", "field": "environment", "condition": "in", "values": ["test", "playground", "sandbox"], "reason": "Non-production outputs are not retained" } ``` Skip drafts ```json { "name": "skip_drafts", "field": "workflowType", "condition": "equals", "value": "draft", "reason": "Drafts are intermediate outputs" } ``` Skip no-action outputs ```json { "name": "skip_no_action", "field": "recommendedAction", "condition": "equals", "value": "none", "reason": "No recommendation was made" } ``` Skip duplicate retries ```json { "name": "skip_retries", "field": "operationalContext.isRetry", "condition": "equals", "value": "true", "reason": "Duplicate retries should not create additional records" } ``` ## Configuring the proxy Set the capture mode and policy file path using environment variables. The proxy reads both at startup; changes require a proxy restart. | Variable | Description | | --- | --- | | CAPTURE_POLICY_PATH | Path to the JSON policy file (for example, /config/capture-policy.json). | | CAPTURE_POLICY_MODE | Capture mode: forward_all, intent_only, or policy. | If CAPTURE_POLICY_MODE is set to policy, the proxy loads the file at CAPTURE_POLICY_PATH on startup. If the file is missing or invalid, the proxy fails closed and rejects all requests until a valid policy is provided. If neither variable is set, the proxy defaults to forward_all mode for backward compatibility. ```bash export CAPTURE_POLICY_MODE=policy export CAPTURE_POLICY_PATH=/config/capture-policy.json ``` ## Local testing Start the proxy locally and exercise the policy with curl against http://localhost:3100/capture. Test both the captured and skipped paths before deploying changes. ### Test a captured request ```bash curl -X POST http://localhost:3100/capture \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "workflowType": "fraud_review", "riskLevel": "high", "environment": "production", "recommendedAction": "escalate", "modelOutput": "Recommend escalation to senior reviewer." }' ``` Expected outcome: the request is forwarded and a decision record is created. ### Test a skipped request ```bash curl -X POST http://localhost:3100/capture \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "workflowType": "draft", "riskLevel": "low", "environment": "test", "recommendedAction": "none", "modelOutput": "Draft summary of meeting notes." }' ``` Expected outcome: the request is skipped locally and the response carries captured: false plus the matching rule name. ### Test invalid policy behavior Point CAPTURE_POLICY_PATH at a non-existent file and start the proxy. The proxy should fail closed and reject requests until a valid policy is provided. > A conservative deployment should avoid forwarding records when policy evaluation fails unexpectedly — for example when the policy JSON cannot be parsed, when required-field definitions are malformed, or when the policy file cannot be loaded at startup. Refusing requests until the policy is valid keeps low-quality or unintended records out of the retained decision record set. ### Test missing required fields Send a request that omits a field listed in requiredFields. The proxy should return an error indicating which field is missing. ## Skipped response behavior When the proxy skips a request, it returns a local response without contacting Verify. The response carries the matching rule name and reason so your application can log the decision or surface it in operational dashboards. ```json { "captured": false, "action": "skipped", "ruleName": "skip_drafts", "reason": "Drafts are intermediate outputs" } ``` - captured: false — the output was not sent to Verify. - action: skipped — the policy decided to skip. - ruleName — which rule matched. - reason — the human-readable reason from the matching rule. Skipped records are not retained in Verify. They exist only in the local proxy response and in whatever logging your application chooses to write. ## Logging and sensitive data The proxy should log only safe decision metadata. AI prompts and model outputs are potentially sensitive — your capture policy controls what reaches Verify, but your logging configuration controls what is written to local logs. ### Safe to log - Rule name that matched. - Capture or skip action. - Workflow type and environment. - Non-sensitive operational identifiers your team uses for retrieval (claimId, encounterId, transactionId, etc.). ### Never log - Prompts or raw model outputs. - API keys, bearer tokens, or any authentication header value. - Secrets, credentials, or session identifiers. - PHI, PII, payment details, or other customer-sensitive payload content. > Treat AI prompts and model outputs as potentially sensitive. The capture policy controls what reaches Verify; local logging controls what reaches your log infrastructure. They are two separate decisions and both belong to your team. ## Recommended policy design A few principles consistently produce policies that age well — and reviewers thank you for later. - Start conservative. Begin with a small set of capture rules targeting your highest-value decisions. Add rules as you understand your workflow patterns. - Capture fewer, higher-value records first. A small set of meaningful decision records is more useful than a large volume of low-value captures. - Review skipped and captured categories during testing. Confirm that rules match the outputs you expect before deploying to production. - Avoid capturing drafts and experiments. These add noise and reduce the signal quality of your retained records. - Align policy to your accountability needs. Capture the outputs you would want to retrieve, review, or verify later — not everything the model produces. - Treat the policy file as a contract. Version it, code-review it, and document the rationale for each rule so the next engineer can extend it without breaking review continuity. ## Troubleshooting Common policy issues and how to resolve them. | Issue | Cause | Resolution | | --- | --- | --- | | Proxy rejects all requests | Policy file is missing or contains invalid JSON. | Confirm CAPTURE_POLICY_PATH points to a valid JSON file. The proxy fails closed on invalid policy. | | No rule matched, request skipped | defaultAction is set to skip and no capture rule matched. | Add a capture rule for the workflow type, or change defaultAction to capture. | | Expected record was skipped | A skip rule matched before the capture rule had a chance to evaluate. | Check skip-rule order. Skip rules always take priority — reorder or tighten the matching condition. | | Too many records captured | defaultAction is capture, or capture rules are too broad. | Set defaultAction to skip and use specific capture rules. Tighten broad workflow-type matches. | | captureIntent not recognized | Using policy mode instead of intent_only mode. | Switch to intent_only mode, or add a capture rule in policy mode that checks captureIntent explicitly. | | Required field missing error | Request payload is missing a field listed in requiredFields. | Confirm the upstream caller includes all fields in requiredFields. Adjust either the request or the requirement. | | Policy not loading | Environment variable not set, path incorrect, or proxy not restarted after a change. | Confirm CAPTURE_POLICY_MODE=policy and CAPTURE_POLICY_PATH are set, then restart the proxy. | For broader integration symptoms beyond the policy itself — authentication, missing records, retrieval failures, verification, Console, Terraform, or CloudFormation deployment issues — see [Troubleshooting Verify Integrations](/resources/troubleshooting-verify-integrations) . ## Production rollout checklist A short operational checklist for moving a capture policy from local testing into a Production environment. - Validate required fields. Every Production request includes the fields listed in requiredFields; the proxy rejects malformed payloads cleanly. - Test captured requests. Representative production-shape requests for each capture rule produce retained decision records as expected. - Test skipped requests. Drafts, playground / test environments, no-action outputs, and duplicate retries are skipped locally and never reach Verify. - Confirm logs exclude prompts, model outputs, secrets, API keys, bearer tokens, and other sensitive payload content. - Confirm CAPTURE_POLICY_PATH points to the intended Production policy file and CAPTURE_POLICY_MODE is set to policy (or intent_only / forward_all if that is the intended mode). - Review a sample of recently retained decision records. Each one should match a workflow your reviewers will recognize as decision-worthy. - Validate environment behavior. Sandbox and Production runtimes use distinct policy files where appropriate, and skip rules correctly exclude non-production environments. - Document the policy. Version the file, code-review it, and note the rationale for each rule so the next engineer can extend it without breaking review continuity. --- --- title: Container / ECS Integration Pattern slug: container-ecs-integration-pattern category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/container-ecs-integration-pattern canonicalUrl: "https://obligra.ai/resources/container-ecs-integration-pattern" llmTags: - llm-aligned - architecture-core - integration - retrieval-tier-3 - supporting-reference --- # Container / ECS Integration Pattern _Architecture_ _Long-running container services — ECS, Kubernetes, or equivalent container runtimes — are where most customer backends already live, and integrating Verify capture from them tends to be a smaller step than customer teams expect at first. The service runs inside the customer’s existing cluster, receives the Verify API key as a runtime secret at container start (not baked into the image), propagates operational context across its request handlers, stays environment-aware, and applies the customer’s existing rolling-deploy discipline. In practice, the operational considerations specific to capture — bounded retries, draining in-flight capture cleanly during deploys, environment-partitioned observability — transfer directly from patterns customer teams already apply elsewhere in the cluster._ ## Overview Container-based services (ECS, Kubernetes, and equivalents) are the most common runtime for long-lived customer backends that host AI-assisted workflows. In practice, most customer teams arrive at Verify with the cluster already in place, the service mesh already configured, the deployment pipeline already standardized — and integrating capture from a container service is, by design, a small additive change rather than a re-architecture. Verify integrates from container services the same way it integrates from any trusted server-side runtime: HTTPS to the public API, environment-scoped credentials, stable operational context attached at capture time. The service runs inside the customer’s existing cluster. Verify’s public API is the boundary. Everything between the two — image build, secret injection, service mesh, scaling policy, observability — is customer-side architecture, which is what allows the customer team to apply their existing container discipline without inventing new conventions for Verify specifically. > Container capture is a customer-side pattern. The service runs in the customer’s cluster. > > > > > Verify does not ship a customer-side container image. Customer teams adopt the pattern using their existing container tooling, secret injection model, and rolling- deploy discipline. ## Why this matters Container runtimes have operational characteristics — long-lived processes, rolling restarts, in-cluster service discovery, sidecar patterns, and image-based deployment — that shape how Verify integration must behave inside the service boundary. Aligning to those characteristics is the difference between a clean container integration and one that surprises the customer team during a rolling deploy. - Images are immutable; secrets must not live in them. A secret baked into an image layer persists in the customer's image registry, propagates across deployments, and is harder to rotate than a runtime-injected secret. - Containers are long-lived; the API key should be loaded once. Re-reading the secret on every request adds latency and load on the customer secret resolver for no security benefit. - Rolling deploys must preserve capture continuity. New pods or tasks should be ready to capture before old ones drain, so no AI-assisted workflow lands in the gap. - In-cluster service discovery is customer-side. Verify is reached via the customer's normal egress — there is no in-cluster Verify service, no sidecar, no mutating webhook. - Observability infrastructure is customer-side. Logs, metrics, and traces emitted from the container ship through the customer's existing platform — credentials must not leak into that path. - Operational context follows the request. In a long-lived service, the workflowId and operationalContext for one request must not contaminate the next; correct propagation is the customer team's responsibility. ## Recommended pattern The recommended customer-side container capture pattern injects the API key as a runtime secret at container start, caches it in process memory, propagates operational context through the request handler, and applies the customer’s existing rolling-deploy discipline. ### Container start (initialization) - Resolve the active environment (Sandbox or Production) from a customer-controlled configuration source. Fail fast on ambiguity. - Receive the environment-scoped Verify API key via the customer's runtime secret injection mechanism — environment variable populated by a task-role-backed secret retrieval, a sidecar secret resolver, a CSI secret driver, or a startup hook that reads from a secret manager. - Cache the API key in process memory; never read from disk and never write it back to disk. - Initialize the HTTP client once at process scope so request handlers reuse the connection pool. - Emit a startup log line confirming the active environment and a non-reversible key reference ("prod-v3") — never the credential value. ### Per-request handling - Receive the request; assemble the request-scoped operational context (workflowId, claimId / encounterId / transactionId / etc.). - Run the AI-assisted workflow step that produces the output to be preserved. - Build the capture payload by combining the request-scoped operational context with the AI-assisted output and any non-sensitive model metadata. - Submit to the Verify Capture API over HTTPS using the cached API key. - Apply bounded retries with exponential backoff and jitter, fitted inside the request's overall budget. Use a stable retry key carried across attempts. - Emit a customer-side log line with environment, workflowId, operational identifier reference, outcome class, retry count, and (if returned) decisionRecordId. Never log the credential value or request headers. ### Rolling deploys - New pods or tasks become healthy (ready to capture) before old ones drain. Configure readiness checks that confirm both the runtime is healthy and the API key has been loaded. - Graceful shutdown gives in-flight requests time to complete capture before the container exits. - The customer's deployment system carries new credentials forward through the rolling deploy — restart-bound secret loads are acceptable, as long as the rollout strategy preserves capture continuity. ## Architecture diagram The diagram below is a customer-safe view of container capture. Every box on the left is customer-owned and sits inside the customer’s cluster; the Verify Capture API is the only external boundary. ```text Customer-owned (customer cluster) Verify (public boundary) ───────────────────────────────── ───────────────────────── Customer Container Cluster (ECS / Kubernetes / equivalent) │ ├─ Customer ingress / load balancer │ │ │ ▼ ├─ Customer Service (one or more tasks / pods) │ │ │ │ (container start) │ ├──────── secret injection ◀── Customer Secret Source │ │ (Secrets Manager / Vault / │ │ Parameter Store / CSI / etc.) │ │ │ │ (per request) │ ├─ Assemble request-scoped operational context │ ├─ Run AI-assisted workflow step │ ├─ Build capture payload │ │ │ │ (HTTPS, X-Verify-Api-Key, bounded retries) │ └────────────────────────────────────▶ Verify Capture API │ │ │ ▼ │ Retained Decision Record │ └─ Customer log / metrics / tracing infrastructure ├─ Outcome class, retry count, env, workflowId └─ decisionRecordId (when returned) Rolling deploy timeline ───────────────────────── t0: old container serving capture t1: new container starts, loads secret, becomes ready t2: load balancer routes to new container t3: old container drains in-flight, then exits Net: zero-gap capture during the rollout ``` ## How it works Container capture is shaped by the long-lived process model — initialization once at start, per-request execution, and deliberate handoff during rolling deploys. ### Initialization Container start runs initialization once. The active environment is resolved from configuration, the API key is injected by the customer’s runtime secret mechanism, and the HTTP client is prepared. The container’s readiness check passes only after these steps succeed — preventing a partially-initialized container from receiving traffic. ### Per-request handling The request handler assembles operational context scoped to the specific request — never reusing context across requests, never letting one workflow’s claimId or transactionId leak into the next. This is a request-scoped discipline that the customer team’s framework should enforce. ### Retry behavior Retries are bounded inside the request’s overall budget. The customer service should track its remaining budget and stop retrying well before upstream timeouts — preferring to return a retryable failure to the upstream caller (or to a customer-side queue) rather than to truncate mid-retry. A stable retry key carried across attempts preserves the retrieval-by-context deduplication path. ### Rolling deploys and graceful shutdown New containers become ready before old ones drain. Graceful shutdown gives in-flight requests time to finish capture before the container exits. The combination produces zero-gap capture during a rollout — even when the rollout changes the API key, the runtime image, or the customer’s framework version. ## Customer responsibilities The customer team owns the cluster, the service, the deployment, the secret injection, the observability, and the operational discipline. Verify owns the public API. The boundary between the two is the HTTPS call. - Provision distinct services or distinct configurations per environment — Sandbox and Production tasks/pods never share credentials. - Inject the API key as a runtime secret at container start using the customer's existing secret injection mechanism — never bake credentials into image layers. - Cache the API key in process memory; never read from disk and never write it back to disk. - Propagate operational context per request; ensure framework-level enforcement that one request's context never contaminates the next. - Apply bounded retries with exponential backoff and jitter, fitted inside the request budget; carry a stable retry key across attempts. - Configure readiness checks that confirm runtime health and successful secret load before the container becomes ready. - Configure graceful shutdown so in-flight capture completes before container exit. - Apply the customer's existing rolling-deploy, canary, and rollback discipline — Verify capture should follow the same SDLC as any other service. - Emit customer-side observability — outcome class, retry count, environment, workflowId, operational identifier reference, decisionRecordId — partitioned per environment and never logging the credential value. ## Common mistakes The pitfalls below are the most common container integration mistakes customer teams encounter. Each one is recoverable, but each one costs avoidable rework — and some surface only during the first rolling deploy after Production rollout. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Baking the API key into an image layer | Secrets in image layers persist in the customer's image registry, propagate across deployments, and are harder to rotate than runtime-injected secrets. | Inject the API key as a runtime secret at container start using the customer's existing secret injection mechanism. | | Reading the secret from disk at runtime | Writing the secret to disk to read it from the container expands the surface where the value can leak (host filesystem, log shippers, image snapshots). | Receive the secret via environment variable populated by the runtime injection mechanism, or via an in-memory secret resolver. Never write to disk. | | Sharing one service across Sandbox and Production | Cross-environment capture happens when configuration drift makes the service read the wrong credential, with no clean failure mode. | Distinct services or distinct configurations per environment. Resolve the active environment explicitly at container start. | | Readiness check returns healthy before secret load completes | Traffic routes to a partially-initialized container; the first requests fail capture before the secret is available. | Readiness check confirms both runtime health and successful secret load. Containers only become ready after the API key is in memory. | | No graceful shutdown handling | Rolling deploys terminate in-flight requests mid-capture, leaving capture status uncertain and producing duplicate records on retry. | Handle SIGTERM, stop accepting new requests, and let in-flight requests complete capture before the container exits. | | Operational context leaks across requests | Request-scoped context stored in process-level state contaminates subsequent requests — one workflow's claimId attaches to the next workflow's record. | Use the framework's request-scoped context primitives (request-local storage, span context, handler-local variables) — never module-level state. | | Logging request headers in error paths | Stack traces and error logs that include the X-Verify-Api-Key header surface the credential in long-term log storage. | Redact authentication headers before any error or trace ships. Audit error-path logging during integration. | | Skipping the rolling-deploy validation in Sandbox | Production rollouts surface deployment-time integration bugs that a Sandbox dry-run would catch. | Perform a rolling deploy in Sandbox, validate capture continuity across the cutover, then promote. | ## Validation checklist Before promoting a container-based Verify integration from Sandbox to Production, the following customer-side controls should all be in place. - Distinct services or distinct configurations per environment — Sandbox and Production tasks/pods never share credentials. - API key is injected as a runtime secret at container start; not present in image layers or source control. - Active environment is resolved explicitly at container start; the service fails fast on missing or ambiguous environment. - Readiness checks confirm both runtime health and successful secret load before the container becomes ready. - Graceful shutdown handles SIGTERM; in-flight requests complete capture before the container exits. - Operational context is request-scoped; framework primitives prevent leakage across requests. - Retries are bounded inside the request budget with exponential backoff and jitter, and carry a stable retry key. - Customer-side observability captures outcome class, retry count, environment, workflowId, operational identifier reference, decisionRecordId — and excludes the API key value and request headers. - A Sandbox rolling-deploy dry-run has confirmed zero-gap capture across the cutover. - The integration follows the customer's existing rolling-deploy, canary, and rollback runbooks. ## Related documentation Pair this guide with the following resources for the full container integration picture: - [Server-Side Capture Pattern — trusted server-side topology container capture sits inside.](/resources/server-side-capture-pattern) - [API Key Placement and Secret Storage — credential discipline for runtime secret injection.](/resources/api-key-placement-and-secret-storage) - [Environment Strategy — Sandbox vs Production discipline across container clusters.](/resources/environment-strategy) - [Operational Context Mapping — retrieval keys propagated per request inside the handler.](/resources/operational-context-mapping) - [Customer Integration Patterns — architecture hub covering container alongside other patterns.](/resources/customer-integration-patterns) - [Queue-Based Capture Pattern — pairs naturally with container-based capture workers.](/resources/queue-based-capture-pattern) - [Network and HTTPS Egress — customer-side network expectations for in-cluster egress.](/resources/network-and-https-egress) --- --- title: Data handling and residency slug: data-handling category: Trust & Security retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/data-handling canonicalUrl: "https://obligra.ai/resources/data-handling" llmTags: - llm-aligned - trust-security - retrieval-tier-3 - supporting-reference --- # Data handling and residency _Trust & Security_ _Verify captures only what the customer team submits. The customer decides — at capture time, inside the customer environment, under the field retention policy — which categories of data become part of a retained decision record and which stay inside the customer’s authoritative systems. Residency, encryption, and access posture follow the customer’s active service contract terms. The data-handling model is intentionally narrow: it is a recipient of governed submissions, not a back-channel to customer-side data sources._ ## Overview Most organizations evaluating Verify arrive with a specific data-handling question: does this product reach into our systems? The answer is deliberately narrow. Verify captures only what the customer team chooses to submit. There is no agent installed inside customer systems, no background process that reaches into source databases, and no query path from Verify into customer environments. The data that becomes a retained decision record arrives over the public HTTPS capture API as a customer-submitted payload — and the customer team controls its shape, scope, and contents. In practice, the goal of data handling for AI-assisted workflows is not to move every detail of a customer’s operational reality into Verify. The goal is to preserve enough decision context that the workflow can be reviewed later, without retaining more sensitive content than the customer team’s review process actually needs. The tradeoff is sharper than it sounds at first — submit too little and review is impossible; submit too much and the customer team carries obligations they did not need to take on. ## Why this matters for GenAI workflows AI-assisted workflows produce decisions whose context is easy to lose. The model version moves on, the prompts change, the surrounding data changes, and the workflow itself gets refactored. By the time a reviewer arrives months later, the inputs the workflow saw at the moment of the decision may no longer exist anywhere except in a retained decision record. That property is what makes the customer’s submission decisions consequential rather than incidental. The tradeoff is sharp in both directions. Submit too little, and reviewers cannot understand what the workflow saw. Submit too much — particularly unnecessary sensitive payloads — and the customer team takes on governance obligations that should not have crossed the boundary in the first place. In practice, the cost of submitting too much is the harder one to walk back: once a sensitive field becomes part of a retained record, retroactively removing it is more expensive than not capturing it in the first place. The right discipline lives between those two extremes. The customer team submits the context required to make the decision reviewable, attaches the operational identifiers reviewers will use to retrieve it, and keeps the rest in the customer’s authoritative systems where it already belongs. ## Verify's role Verify acts as a recipient and preservation layer for customer-submitted decision context. The role is bounded intentionally so that data flow remains in the customer’s control. - Receive only what the customer submits over the public capture API. There is no separate pull, sync, or crawl mechanism into customer systems. - Preserve the submitted context as a retained decision record indexed by customer-attached operational context. - Support retrieval of the retained record by the same operational context the customer team already uses. - Apply modern encryption in transit (HTTPS / TLS 1.2 or higher) and modern encryption at rest to retained records. - Expose review surfaces (Verify Console, retrieval and verification APIs) to customers whose teams need to inspect retained records. The customer’s authoritative system of record remains the source of truth. Verify does not replace it; Verify preserves the context that makes specific AI-assisted decisions reviewable later. ## Customer responsibility The customer team owns the submission decisions, and the submission decisions shape the data-handling posture of the entire integration. The most consequential decisions are made up-front, during integration design. ### What to submit The customer team decides which workflows produce records, which fields are included in each record, which operational identifiers are attached as retrieval keys, and which customer-side surfaces consume the resulting records. Each choice is shaped by the customer’s regulatory environment, the review process, and the workflow itself. ### What to keep in customer systems The customer team also decides what does not cross the boundary. Full PHI or PII payloads, raw transaction bodies, full case files, source-system snapshots — these typically belong only in the customer’s authoritative systems. The retained decision record carries the context needed for review; the authoritative system continues to carry the full operational state. ### How to evolve submissions over time As the AI-assisted workflow matures, the customer team may refine what each submission carries. The discipline is additive — add fields the review process actually needs, remove fields that are not used in review, and keep the shape stable enough that prior records remain retrievable and reviewable under the same conventions. ## Data categories and guidance The table below summarizes the data categories typically involved in an AI-assisted workflow and the customer-side guidance that applies to each. The exact fields are customer-defined; the guidance is consistent. | Data category | Example | Guidance | | --- | --- | --- | | Workflow identifier | claims-review, fraud-triage, post-visit-summary, complaint-handling | Use stable workflow names that the customer team already uses operationally. Treat the name as a contract — do not rename it across releases. | | Operational context | claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId | Use recognizable business identifiers issued by the customer's authoritative systems. These become the retrieval keys reviewers will use months later. | | Model metadata | model.provider, model.modelId, prompt version reference | Preserve model context where available so reviewers can later understand which model produced the decision. Avoid including secrets or proprietary prompt internals. | | Prompt and output context | AI-assisted context fields the customer chooses to retain | Include what is needed for later review. Avoid embedding unrelated business state, customer-system snapshots, or sensitive identifiers that the review process does not require. | | Review metadata | status, timestamps, reviewer activity references | Preserve review-oriented workflow context that supports later inspection. Reviewer identity should follow the customer's existing access discipline. | | Sensitive content not required for review | Raw PHI, raw PII payloads, full source-system snapshots, unrelated business data | Avoid submitting more than the workflow requires. Keep this content inside the customer's authoritative systems where it already belongs. | ## What customers submit vs what Verify preserves The flow below reinforces the discipline visually: customer workflows produce a wide operational reality; the customer team selects the slice that becomes a retained decision record; Verify preserves that slice and supports later retrieval and review. Submit what supports later review — not everything the workflow happens to know. ```text Customer side Verify (public boundary) ───────────── ───────────────────────── Customer AI-assisted Workflow │ │ (1) Workflow produces a full operational picture │ across customer authoritative systems ▼ Customer Submission Decision │ │ (2) Customer chooses the slice that supports │ later review: │ • workflowId │ • operationalContext │ (claimId, encounterId, transactionId, │ escalationId, policyId, reviewCaseId, ...) │ • AI-assisted context (selected) │ • model metadata (provider, modelId) │ • review metadata (status, timestamps) ▼ Capture submission │ │ (3) HTTPS POST over standard public TLS ▼ │ ▼ Verify Retained Decision Record │ │ (4) Indexed by operational context │ for later retrieval ▼ Later Retrieval and Review │ │ (5) Reviewers retrieve by the │ same operational identifiers │ the customer team uses │ day-to-day ▼ Customer Review Workflow Customer Authoritative Systems (claims platform, EHR, accounting platform, CRM, policy admin) │ │ Full operational state continues to live here. │ Verify does not duplicate or replace authoritative systems. ``` Two principles run through the diagram. First, the customer team chooses the slice — Verify never reaches into source systems to pull more. Second, the authoritative system remains the source of truth; the retained decision record carries the slice that makes one specific AI-assisted decision reviewable later. ## Residency considerations Residency for retained decision records depends on the active service contract and the deployment configuration in place for the customer. The right approach for an enterprise integration is to evaluate available residency options against the customer’s regulatory environment, the AI-assisted workflows in scope, and the customer’s existing data-classification program. - Confirm the residency options available under the customer's active service contract and deployment configuration before integration design. - Confirm how Sandbox and Production residency are described, since records do not move between environments. - Align residency selection with the customer's existing regulatory and contractual obligations — Verify operates within the chosen configuration, not above it. - Document residency for the AI-assisted workflows in scope inside the customer's internal program — the same documentation discipline that applies to other SaaS integrations. - Treat residency as a customer-side architectural decision evaluated during integration planning, not as a runtime knob. ## Encryption and access considerations Encryption posture and access discipline span both sides of the boundary — Verify applies modern encryption to retained records and exposes authenticated APIs, while customer teams control credentials, runtime access, and downstream review access. ### Encryption Verify applies modern encryption in transit (HTTPS over TLS 1.2 or higher) and modern encryption at rest to retained decision records. Specific cipher minimums, key management, and protocol details are described in the active published service description rather than invented here. ### Access The public capture API is reachable only with an environment-scoped API key held inside trusted customer server-side runtimes. The Verify Console exposes retained records to authorized customer users through the customer’s configured access. All customer-side identity, role, and access decisions live inside the customer’s existing identity program. ### Audit trail Customer-visible audit information about access to retained records (who retrieved what, when) is exposed where applicable for the customer’s review program. Internal platform telemetry remains internal to the platform. ## Common implementation mistakes The implementation mistakes below are the most common customer-side data-handling pitfalls during integration design. Each one is recoverable, but every recovery costs governance time the team did not need to spend. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Submitting full source-system payloads at capture time | Inflates the data scope of the integration, expands governance obligations, and obscures the small slice that actually supports review. | Submit only the context the review process requires. Keep authoritative state inside the customer's source systems. | | Embedding PHI or PII inside operational-context identifiers | Identifiers should name the work, not embed the content of the work. Embedding sensitive content expands the surface where it can appear. | Use non-sensitive customer-side references (record-system patient references, account references, etc.) that name the work without embedding sensitive payloads. | | Treating Verify as a place to store everything that might be useful later | Verify is for AI-assisted decision records. Sending unrelated business data turns the retrieval surface into a noisy store and dilutes review focus. | Scope submissions to AI-assisted decisions. Other business data continues to live in the systems that already own it. | | Skipping the residency conversation until Production rollout | Residency decisions made late often require re-evaluating the deployment configuration and slow down rollout. | Confirm residency options against the customer's active service contract and the AI-assisted workflows in scope during integration planning. | | Mixing Sandbox and Production data inside the same submission shape | Sandbox payloads contaminate Production review surfaces, and test identifiers leak into the operational retrieval contract. | Distinct environments, distinct submission shapes where appropriate, and explicit environment confirmation on every submission. | | Logging the API key or full request body for debugging | Credentials and payload content end up in long-term log infrastructure with the customer's retention policy. | Log outcome class, retry count, environment, and a key reference. Redact authentication headers and request bodies. | | Renaming operational-context fields across releases | Records captured under the old shape become harder to retrieve under the new shape; reviewers lose retrieval continuity. | Treat operational-context field names as a contract. Add new fields when the vocabulary genuinely grows; do not silently rename existing ones. | ## Related documentation Pair this guide with the following pages for the full data-handling and integration picture: - [Security overview — Shared Responsibility Model and the broader security posture.](/resources/security-overview) - [Record integrity and verification — customer-visible verification model for retained records.](/resources/record-integrity-and-verification) - [Compliance approach — how retained records support audit and review programs.](/resources/compliance-approach) - [Operational Context Mapping — how customers choose identifiers that survive the data-handling boundary.](/resources/operational-context-mapping) - [Structure of a decision record — the customer-visible record shape.](/resources/structure-of-a-decision-record) - [Environment Strategy — Sandbox vs Production separation across submitted data.](/resources/environment-strategy) --- --- title: Environment Strategy slug: environment-strategy category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/environment-strategy canonicalUrl: "https://obligra.ai/resources/environment-strategy" llmTags: - llm-aligned - architecture-core - integration - retrieval-tier-3 - supporting-reference --- # Environment Strategy _Architecture_ _Most Verify integration friction during Production rollout traces back to environment discipline that was either taken for granted or never validated end-to-end in Sandbox. Sandbox and Production are independent customer-facing environments — separate API keys, separate retained decision records, separate retrieval surfaces, separate review queues — and organizations that treat them as a single coordinated cutover, rather than two interchangeable copies of the same surface, ship Production rollouts with predictable behavior. This guidance covers what each environment is for, what stays environment-aware end-to-end, the Sandbox-first validation loop that makes Production behavior predictable, and the promotion discipline that keeps Sandbox activity out of Production review._ ## Overview Organizations rolling Verify into Production for the first time consistently encounter the same architectural question: how should Sandbox and Production relate to each other? The answer Verify is built around is that they should not relate to each other at all. Each is an independent customer-facing environment, and that independence is enforced from the credential at capture time through to the downstream review surface a reviewer uses months later. In practice, environment discipline is one of the highest-leverage customer-side decisions during onboarding. Teams that walk a single workflow through Sandbox end-to-end before issuing a Production credential tend to ship clean Production rollouts; teams that treat Sandbox as a temporary scaffold to be bypassed under deadline pressure tend to discover environment-crossover issues during their first compliance review. The cost of the discipline is low. The cost of skipping it surfaces late, in the surfaces customers care about most. > Validate Sandbox end-to-end before any Production rollout. > > > > > One workflow captured, retrieved, inspected, and verified in Sandbox is the foundation of a confident Production rollout. Skipping the dry-run is the single most common source of avoidable Production friction. ## Why environment separation matters The reason environment separation matters in Verify is straightforward: Verify is a retrieval-oriented system of record, and the consumers of that record — reviewers, operational dashboards, compliance and audit programs, engineering teams — each rely on a different facet of environment integrity. When the boundary holds, each consumer gets the guarantee they implicitly expect. When it slips, the failure modes are subtle, surface late, and erode review confidence in ways that are difficult to walk back. In practice, the consequences play out along four lines. Reviewers need confidence that a record retrieved during a Production review is a Production record — not a test record that drifted into the same retrieval surface. The tradeoff for skipping this discipline is hard to spot in the short term and corrosive over a longer one: reviewers quietly lose trust in the records they are reviewing, and the operational program weakens around them. Operational dashboards depend on a clean line between Sandbox capture and Production capture so on-call engineers can read signal from noise; without that line, alert fatigue follows. Compliance and audit programs assume that Production review draws only from Production records, and that Sandbox activity stays outside the audit scope. Customer engineering teams need a place to onboard, integrate, and validate without producing review-bearing records that surface to operators — and the trust boundary for capture itself depends on credentials that authorize one environment and one environment only. ## Sandbox vs Production Each environment exists to serve a different operational reality, and the difference is worth being explicit about because customer teams routinely have to decide which one a particular runtime, dashboard, or review surface belongs in. ### Sandbox Sandbox is where engineering teams onboard, where integration tests run, where workflow validation happens, and where operators practice retrieval before it matters in Production. It is intentionally permissive in the way most pre-production environments are: the goal is to exercise the integration end-to-end against representative payloads without producing records that downstream operators will act on. Records captured in Sandbox carry an explicit Sandbox environment marker, so any system that retrieves them knows what it is looking at — which becomes important when a reviewer unexpectedly hits a Sandbox-credentialed surface and needs to recognize it on sight. ### Production Production carries live operational workflows. Records in Production reflect real claims, encounters, transactions, escalations, policies, or cases — the artifacts customer review surfaces, dashboards, compliance programs, and audit teams will actually consume. In practice this means Production records sit inside the customer’s existing review and audit scope, follow the customer’s Production-grade operational discipline (credentials, runbooks, observability, incident response), and are the records reviewers ultimately rely on when an operational decision needs to be defended. ## A capture boundary per environment As customer teams move into governed deployments, the environment boundary usually has to extend beyond credentials and retrieval surfaces. Organizations often discover during their first compliance review that a single proxy serving both environments has become a blast-radius problem: a permissive Sandbox capture policy applied to Production traffic, even briefly, surfaces in audit as a category of incident that takes weeks to explain. The recommended architectural response is straightforward — deploy a separate Customer-Owned Capture Boundary per environment, so the proxy and the capture policies that govern Sandbox traffic are distinct from those that govern Production traffic. The resulting shape is symmetrical, environment by environment: ```text Sandbox Environment │ ▼ Sandbox Proxy │ ▼ Sandbox Policies Production Environment │ ▼ Production Proxy │ ▼ Production Policies ``` The detailed mechanics of the boundary, the proxy, and the policies live in [Deployment Topology](/resources/deployment-topology) and [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . The point to carry forward from here is architectural: the proxy and the policies belong on the same per-environment axis as the credential, and the customer team that scopes all three together will avoid the most common governance drift during Production rollout. ## What stays environment-aware Environment-awareness is not a property of any single component. It is a posture that has to hold across every customer-side surface that touches a retained decision record — from the credential a runtime reads at startup, through the capture call itself, into the retrieval and verification surfaces operators use during review, and out into downstream dashboards, queues, and observability. The discipline holds only as well as the weakest link in that chain. The components below are the surfaces where environment-awareness most often slips during a first integration. The table is worth reading as a survey of where confusion typically enters — each row is a place that, in our experience, rewards a deliberate per-environment decision early rather than a default that gets discovered later. | Component | Environment-aware guidance | | --- | --- | | API keys | Distinct keys per environment. Sandbox keys cannot submit Production records, and Production keys cannot submit Sandbox records. Generate, store, and rotate independently. | | Secret manager paths | Distinct secret-manager entries or namespaces per environment. Sandbox and Production credentials should not share a secret entry — and access should be scoped per environment. | | Customer backend runtime config | Each runtime receives the credential for its environment. Confirm the active environment at runtime before the first capture call. Do not allow runtime config to silently fall back to a different environment. | | Capture endpoints | Submission routes for capture are environment-scoped. The customer backend uses the host or surface configured for the active environment from the Verify Console. | | Retrieval and verification surfaces | Retrieval, inspection, and verification calls are environment-scoped. A Sandbox retrieval call cannot return Production records and vice versa. | | Downstream queues and dashboards | Customer-side queues, review queues, dashboards, and operational tools that consume Verify activity should be scoped per environment. Sandbox events should never advance Production cases. | | Observability and alerting | Customer-side logs, metrics, traces, and alerts should be partitioned per environment so an on-call engineer can tell Sandbox noise from Production signal at a glance. | | CI/CD pipelines | Pipeline stages should inject the right environment's credential at the right step. Promote workloads to Production only after a clean Sandbox validation run. | | Customer-Owned Proxy | In governed deployments, deploy a separate proxy per environment. Sandbox traffic is governed by the Sandbox proxy; Production traffic is governed by the Production proxy. They share the credential-discipline rules above but operate as distinct runtimes. | | Capture Decision Policy | Sandbox policies may be more permissive to support onboarding and validation. Production policies typically apply stricter capture rules so only review-worthy interactions become retained decision records. | | Field Retention Policy | Sandbox retention may allow more fields to support engineering and validation. Production retention typically applies stricter allow/redact/truncate/drop/neverForward rules aligned to the customer's compliance posture. | ## The Sandbox-first validation loop Most Production rollouts that go wrong went wrong before the Production credential was ever issued. The recommended counter to that pattern is a deliberate Sandbox dry-run of the full capture-and-review path against a representative workflow. The point is not just to confirm that capture works — the point is to surface every operational decision the integration is making, in the environment where surfacing them is safe. A clean Sandbox loop produces a confident answer to a single, concrete question: when this same integration runs in Production, will the record reach reviewers in a shape that supports the way they actually work? The loop exercises capture, retrieval by operational identifier, inspection of the resulting record, and verification of its integrity — in that order, because each step builds on the previous one. In practice, when a downstream issue surfaces during Production review, the customer team can almost always trace it back to a step in this loop that was skipped or run too narrowly. The recommended sequence is: - Generate a Sandbox API key from the Verify Console. Store it in the customer's secret manager under a Sandbox-scoped entry. - Configure a customer backend runtime to read the Sandbox credential and confirm at process start that the active environment is Sandbox. - Run an AI-assisted workflow end-to-end against the Sandbox runtime — produce an output, attach stable operational context, submit the retained decision record. - Retrieve the record back using the same business identifier reviewers will use day-to-day in Production (claimId, encounterId, transactionId, escalationId, policyId). - Inspect the record — confirm workflowId, operational context, AI-assisted context, model metadata, timestamps, and verification state all look correct. - Run verification on the record. Confirm the verification call returns the expected customer-visible state. - Confirm activity history in the Verify Console shows the expected Sandbox capture, retrieval, and verification activity for the workflow. - Repeat across the operational shapes Production will see — different operational identifiers, different AI-assisted output shapes, different downstream review paths. - Promote to Production only after the Sandbox loop is clean. Use a separate Production API key, separate downstream review surfaces, and separate dashboards. ## Records do not move between environments A retained decision record lives in the environment it was captured against for its entire lifecycle. There is no customer-side workflow that promotes a record across the boundary, and that constraint exists by design — it is what allows reviewers to trust the environment marker on a record they retrieve six months later. The discipline applies equally in both directions and at every surface that touches the record. The retrieval surface is environment-scoped end-to-end. A Sandbox-credentialed retrieval cannot return Production records, and a Production-credentialed retrieval cannot return Sandbox records. Verification follows the same rule: a verification call is scoped to the record’s home environment, and a Sandbox record’s verification result has no operational meaning in a Production review. Retention applies inside the home environment; promotion does not extend a Sandbox retention into Production. And operational review of a Production workflow draws only from Production records. The practical consequence for customer teams is that Sandbox cannot serve as a staging ground for “almost-real” records that will later be promoted into Production evidence. The tradeoff is intentional: the boundary is what protects the integrity of the Production record set. Sandbox proves the integration; Production carries the records. > Do not use Sandbox records as Production evidence. > > > > > Confirm the active environment before any review, escalation, or downstream operational action. A retrieved record’s environment value should always be checked before it is acted on. ## Environment-aware retrieval and verification Environment-awareness extends past capture into the retrieval and verification surfaces operators rely on for review. In practice, retrieval calls inherit the credential scope of the calling system — a Sandbox-scoped session retrieves Sandbox records, a Production-scoped session retrieves Production records — and that scoping is precisely what protects reviewers from acting on the wrong record at the wrong moment. The most common reason a retained record appears missing during a first integration is wrong-environment retrieval. A team is looking in Sandbox for a record that was captured in Production, or the reverse, and the absence reads as “Verify lost the record” when in fact the integration is working exactly as designed. Confirming the active environment before assuming a record is missing resolves the majority of these reports — and it is usually the first runbook entry a customer team adds after the second occurrence. Customer-side review tooling can reinforce the boundary by branching on the environment value of a retrieved record before acting on it. The recommended pattern is that reviewers see the environment of every record at a glance, and review surfaces refuse to advance a case when the record’s environment does not match the expected scope. Verification follows the same scoping — a verification call is bounded to the record’s home environment, and inspection surfaces should display the environment value alongside the record so reviewers can confirm scope at a glance. ## Promotion to Production Promotion to Production is a customer-side cutover, not a Verify platform action. The Verify platform does not move credentials, records, or downstream review surfaces across environments — the customer team makes that cutover, and the customer’s deployment system carries it out using the same staged-deploy or canary discipline already applied to other high-impact services. The architectural objective at promotion time is straightforward: ensure the Production runtime sees a Production credential, ensure downstream Production surfaces accept Production records only, and ensure observability is partitioned so the cutover is visible to whoever is on call when it happens. ### Recommended promotion sequence - Confirm the Sandbox validation loop is clean — capture, retrieve, inspect, and verify all pass against representative payloads. - Generate a Production API key from the Verify Console. Store it in the customer's secret manager under a Production-scoped entry, distinct from the Sandbox entry. - Configure a Production runtime to read the Production credential and confirm at process start that the active environment is Production. - Wire downstream Production surfaces — operational dashboards, review queues, customer-side observability — and confirm they accept Production records only. - Roll out to Production behind whatever staged-deploy or canary discipline the customer team already uses for high-impact services. - Monitor customer-side observability for the cutover. Capture outcomes, retrieval health, and verification results should match Sandbox behavior at steady state. - Document the promotion in the customer's runbook so the next team member who onboards a workflow can follow the same loop. ## Builder to governed Production journey Most organizations follow a recognizable arc from first-time integration to a production-ready deployment, and naming the stages explicitly is the cheapest way to plan it. The arc begins in a builder workspace, runs through the Sandbox validation loop, and crosses into a governed Production deployment with the credential, the proxy, and the capture policies all environment-scoped together. In practice, engineering teams that lay out the stages in this shape before they start writing integration code consistently report a smoother path to Production than teams that discover the stages incrementally under deadline pressure. ![Environment Promotion Strategy. Six-stage horizontal progression from Builder workspace to Production records. Stage 01 Builder Workspace: first integration walk-through covering setup, initial implementation, and local testing. Stage 02 Sandbox Environment: the validation loop covering capture, retrieve, inspect, and verify. Stage 03 Validation Complete: milestone with all four Sandbox checks passing against representative workflows. Stage 04 Production Preparation: distinct everything — separate credentials, separate review surfaces, separate governance controls. Stage 05 Governed Production Deployment: governance enforced — Customer-Owned Proxy, Capture Decision Policy, Field Retention Policy. Stage 06 Production Records: review-ready, with reviewers retrieving records by operational context. Footer caption: environment separation, credential discipline, and capture governance together preserve review integrity from first integration through production review.](/diagrams/obligra-verify-environment-promotion-strategy.svg) * Environment promotion strategy from Builder workspace to governed Production deployment. Each stage introduces additional controls: the Sandbox loop validates the integration; the promotion step separates credentials, review surfaces, and governance; the production deployment adds the customer-owned proxy and the two capture policies. * ## Logging and observability per environment Customer-side observability around capture follows the same rules customer teams already apply to other production systems: signal and noise have to be separable, and an on-call engineer paged at 3am should be able to tell Sandbox activity from Production signal without thinking about it. Verify does not substitute for that customer-side observability program. What changes when capture is environment-aware is that the program now has a concrete axis to partition on. The recommended pattern is the one most engineering teams already use elsewhere: tag every log line with the active environment, partition metrics and dashboards so Production capture rates and verification outcomes are not mixed with Sandbox numbers, route Production-scoped alerts through the customer’s full incident response pathway, and keep Sandbox-scoped alerts at a lower severity. In practice, the discipline pays for itself the first time a Production incident surfaces and the on-call engineer can filter Sandbox noise out of the timeline at a glance. Log retention typically follows the customer’s existing audit retention for Production and a shorter engineering retention for Sandbox. Log shippers should never cross environments — a Sandbox log line landing in a Production observability surface is the same category of failure as a Sandbox record landing in a Production retrieval call, and it should be treated with the same seriousness. For the customer-side logging discipline that surrounds the credential itself, see [API Key Placement and Secret Storage](/resources/api-key-placement-and-secret-storage#logging-and-observability) . ## Common mistakes The mistakes below are the ones that surface most often during onboarding and Production rollout. They appear here not because they are exotic, but because they are the patterns where confidence in the integration tends to break before review starts. In practice, walking the list before promotion is a low-cost way to find them in Sandbox rather than in Production, where the cost of finding them is much higher. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Sharing one API key across Sandbox and Production | Breaks the credential boundary that enforces environment separation; a single rotation impacts both environments, and capture can drift across environments by accident. | Distinct keys per environment, distinct secret-manager paths, environment-scoped access. | | Skipping the Sandbox validation loop | Production rollout becomes the first time the customer team observes capture, retrieval, inspection, and verification end-to-end — every issue surfaces under real review pressure. | Capture, retrieve, inspect, and verify one workflow end-to-end in Sandbox before any Production credential is provisioned to a runtime. | | Mixing Sandbox and Production downstream review surfaces | Reviewers cannot tell test records from real records; operational dashboards and audit programs become unreliable; review confusion compounds over time. | Distinct dashboards, distinct queues, distinct review surfaces per environment. Sandbox events do not advance Production cases. | | Falling back silently to a different environment at runtime | Runtimes that default to one environment when configuration is missing produce records in the wrong environment without any clear failure mode. | Confirm the active environment at process start. Fail fast on missing or ambiguous environment configuration. | | Assuming records can be promoted from Sandbox to Production | Records do not move between environments. Plans that depend on Sandbox-record migration will fail under the customer's audit posture. | Use Sandbox to validate that the loop works. Capture real records against Production credentials once Production is ready. | | Logging across environments into one observability surface | On-call engineers cannot tell Sandbox noise from Production signal; alerts lose their meaning over time. | Tag every log line with the active environment, partition metrics and alerts per environment, route Production alerts through customer incident response. | | Allowing Sandbox-credentialed services to call Production datasets | Even when Verify capture stays correct, the customer side ends up with a runtime that holds a Sandbox credential but acts on Production business data — a category mismatch that surfaces as review confusion later. | Treat the active Verify environment as one signal in the customer team's broader environment-discipline posture across runtimes and data paths. | ## Validation checklist Promotion from Sandbox to Production is the moment in a rollout where it is easiest to miss a control because the integration “just works.” The checklist below is a final pass that confirms environment discipline holds end-to-end before Production traffic begins flowing into review surfaces. It is intentionally narrow — the customer team’s deployment program will have its own controls layered on top — but it captures the controls that, in practice, matter most for review confidence in the first weeks after Production rollout. Before promoting a workflow: - Distinct Sandbox and Production API keys exist — generated separately from the Verify Console, never shared. - Distinct secret-manager paths or namespaces hold each environment's credential — Sandbox and Production credentials do not share an entry. - Customer backend runtimes confirm the active environment at process start before the first capture call. - Sandbox capture, retrieval, inspection, and verification have all been validated end-to-end against representative workflows. - Operational identifiers used in Sandbox match the shape Production will use — claimId, encounterId, transactionId, escalationId, policyId. - Production downstream surfaces are environment-scoped — dashboards, queues, review surfaces, and operational tools accept Production records only. - Customer-side observability is partitioned per environment — logs, metrics, alerts, and retention all reflect the environment they describe. - CI/CD pipelines inject the right environment's credential at the right step and do not silently cross environments. - A promotion runbook is documented — who promotes, how, what is checked, what happens if Production behavior diverges from Sandbox. - Operators understand the environment value of every retrieved record before acting on it. ## Related documentation The pages below cover the architectural decisions environment strategy depends on most directly: where the credential lives, how the boundary is shaped, how the capture policies are designed, and how the deployment fits into the customer’s existing infrastructure. - [Install and Configure Verify — canonical first-time developer onboarding loop including the Sandbox-first validation pattern.](/resources/install-and-configure-verify) - [Server-Side Capture Pattern — trusted server-side capture topology, environment-aware capture rules.](/resources/server-side-capture-pattern) - [API Key Placement and Secret Storage — per-environment credential storage discipline.](/resources/api-key-placement-and-secret-storage) - [Deployment Topology — where the Customer-Owned Capture Boundary sits per environment, and how the credential, proxy, and policies are placed inside it.](/resources/deployment-topology) - [Customer Integration Patterns — direct, governed, and proxy-fronted integration shapes that environment planning depends on.](/resources/customer-integration-patterns) - [Configuring an AI Capture Policy — environment-scoped Capture Decision Policy and Field Retention Policy guidance.](/resources/configuring-an-ai-capture-policy) - [Reference Architecture: AWS — concrete deployment topology for the customer-owned capture boundary inside a customer AWS account.](/resources/reference-architecture-aws) - [Operational Context Mapping — environment-aware retrieval keys for retained decision records.](/resources/operational-context-mapping) - [Verify API Reference — first-time-user API reference including environment handling on every call.](/resources/api-reference) - [Verify SDK Reference — capture SDK environment-aware onboarding and operational context guidance.](/resources/verify-sdk-reference) - [Webhook Events — environment-aware webhook delivery for customer-side downstream surfaces.](/resources/webhooks) - [Customer Security Overview — broader customer-side security posture around Verify integrations.](/resources/security-overview) - [From Sandbox to Production — how environment strategy fits into the four-stage adoption maturity arc and which governance milestone each environment unlocks.](/resources/from-sandbox-to-production) --- --- title: Implementing Verify in a Customer Workflow slug: implementing-verify-in-a-customer-workflow category: Developers retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/implementing-verify-in-a-customer-workflow canonicalUrl: "https://obligra.ai/resources/implementing-verify-in-a-customer-workflow" llmTags: - llm-aligned - integration - implementation-guide - retrieval-tier-3 - supporting-reference --- # Implementing Verify in a Customer Workflow _Developers_ _Connecting a backend workflow to Verify is a single architectural action with five reliably ordered steps: submit selected decision context after the AI-assisted step, receive a capture receipt, retrieve the retained decision record by operational context, confirm what the reviewer will see, and verify the result in the Verify Console. In practice, the cost of getting this loop right once is small, and the cost of skipping any step surfaces during the first review the workflow encounters — which is precisely when the team that built the integration has the least bandwidth to revisit it._ ## What this guide covers This guide walks through the first working integration between a customer backend workflow and Obligra Verify. It assumes you have already prepared your environment by following the Quickstart, or that you already have the access and tooling listed there. By the end of this guide, you will have: - Configured the Verify SDK. - Chosen a stable workflow ID. - Selected the decision context to send. - Submitted one retained decision record. - Reviewed the capture receipt. - Found the record in the Verify Console. - Inspected the record detail page. - Verified the record. - Understood common implementation issues. Your application remains the system that runs the workflow. Your model provider remains the system that generates the AI-assisted output. Verify becomes the system of record for the decision evidence created around that output. ## Before you begin Before following this guide, complete the [Quickstart](/resources/quickstart) or confirm that you already have: - Verify Console access - Workspace access - Sandbox environment - Environment-scoped API key - Backend runtime (Node.js 18 or later for the Verify SDK) - Secure key storage (secret manager or environment variable store) - Outbound HTTPS access to the Verify API - Safe test payload (fake, redacted, or approved sample data) If any of these are missing, return to the Quickstart and complete the setup-readiness path before continuing. ## Step 1. Install the Verify SDK Install the Verify SDK in the backend service, worker, API route, or job processor that will submit selected decision context to Verify. Do not install or use the SDK in browser code for production API-key usage. ```bash npm install @obligra/verify ``` Or with Yarn: ```bash yarn add @obligra/verify ``` Or with pnpm: ```bash pnpm add @obligra/verify ``` The SDK is intended for server-side use. It should run inside the workflow service, API backend, job processor, orchestration layer, or integration service that already has access to the relevant workflow context. Do not bundle it into a browser application or a mobile app. > **Checkpoint.** You are ready to continue when the Verify SDK is installed in your backend project. ## Step 2. Configure the Verify client The client is the small object your code uses to call Verify. You create it once during application startup and reuse it for every capture call. The client reads the API key and environment from environment variables, so the key never appears in source code. ```typescript import { VerifyClient } from "@obligra/verify"; const verify = new VerifyClient({ apiKey: process.env.OBLIGRA_VERIFY_API_KEY!, environment: process.env.OBLIGRA_VERIFY_ENVIRONMENT || "sandbox" }); ``` Where the values come from: - apiKey is read from the environment variable you set in Step 4. - environment is read from a second environment variable, with sandbox as the default if it is not set. This makes it harder to accidentally send sandbox records to production. For production applications, initialize the client once at application startup and reuse it across requests. Do not create a new client per request — that is unnecessary and wastes connections. ## Step 3. Choose the workflow ID Before you send a record, decide which workflow is producing the AI-assisted output. A workflow ID is a stable name for the business process that created the AI-assisted output. Examples of workflows: - Clinical summary generation - Insurance claim routing - Fraud review assistance - Customer support classification - Loan document review - Transaction dispute review - Policy exception analysis Examples of workflow IDs: - wf-clinical-summary-v1 - wf-claim-routing-v1 - wf-dispute-review-v1 The workflow ID should be stable across many records. Do not generate a random workflow ID per record — that breaks retrieval. The same workflow that runs a thousand times a day should produce a thousand records that all share the same workflow ID. Each individual record is then identified by its own decision record ID and operational context, not by a unique workflow ID. Pick the version suffix carefully. If the underlying business process changes in a meaningful way (new model, new policy, new prompt template), bump the suffix to v2 so review teams can tell the cohorts apart. ## Step 4. Choose the selected decision context Selected decision context is the specific fields the customer chooses to send to Verify so the record can be found and reviewed later. Choose enough context to support later retrieval, review, and verification — but no more sensitive data than necessary. A common mistake is to send the entire request payload "just in case." That increases retention obligations, increases review surface area, and may expose data that should have stayed in the source system. ### Good fields to send - Workflow ID (stable name for the business process) - Case ID, claim ID, encounter ID, transaction ID, or the equivalent business identifier - Generated output ID, summary ID, or routing decision ID - Model provider (for example Anthropic, OpenAI) - Model ID (for example claude-sonnet-4) - Validation state (for example passed, failed, skipped) - Review status (for example pending, approved, rejected) - Service name, region, request ID, and similar troubleshooting metadata ### Avoid sending unless explicitly approved - Full medical records - Full financial account details - Unnecessary personal data - Secrets, tokens, or credentials - Raw source documents that should stay in the customer system Where possible, send a stable reference (such as an `s3://` URI or an internal record ID) rather than the raw content. The reference points to the customer-owned source material; the retained decision record stays compact. ## Step 5. Submit your first retained decision record After your workflow produces an AI-assisted output, call Verify with the selected decision context you want retained. The example below uses the Verify SDK; the API equivalent is shown later on this page. ```typescript const receipt = await verify.records.create({ workflowId: "wf-clinical-summary-v1", environment: "sandbox", operationalContext: { encounterId: "enc-84721", patientVisitId: "visit-39281", generatedSummaryId: "sum-77129" }, model: { provider: "anthropic", modelId: "claude-sonnet-4", modelVersion: "2026-02-15" }, prompt: "Summarize the telehealth encounter for the attending clinician...", response: "Generated visit summary text...", validationState: "passed", reviewStatus: "pending", metadata: { service: "clinical-summary-service", region: "us-east-1", requestId: "req-93f72a" } }); console.log(receipt.decisionRecordId); console.log(receipt.recordUrl); ``` What each main section of the payload does: - **workflowId** — Identifies the business process that produced the AI-assisted output. - **environment** — Routes the record to sandbox, staging, or production. Must match the environment of the API key being used. - **operationalContext** — The business identifiers (encounter ID, claim ID, transaction ID, and so on) that make the record searchable later. - **model** — Identifies the provider and model that produced the output. Used during review to understand which model the record came from. - **prompt** — Prompt or input text submitted to the model. Part of the canonical capture model. In governed deployments this field may be subject to the customer's field retention policy. - **response** — Response text returned by the model. Part of the canonical capture model. In governed deployments this field may be subject to the customer's field retention policy. - **validationState and reviewStatus** — Describe the current review state of the record at capture time, for example 'passed' validation and 'pending' review. - **metadata** — Optional service, region, and request ID details that help with troubleshooting and operational filtering. Send only the decision context your retention and data-handling policies allow. The first test should use safe sample data rather than real production data. > **Checkpoint.** You are ready to continue when the API response includes `status: recorded` and a `decisionRecordId`. ## Step 6. Review the capture receipt A successful create request returns a capture receipt. The capture receipt is proof that the request reached Verify and a retained decision record was created. It does not return the full retained record — it returns the identifiers needed to retrieve and verify the record later. Example response: ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "status": "recorded", "verificationState": "verifiable", "workflowId": "wf-clinical-summary-v1", "environment": "sandbox", "createdAt": "2026-05-01T17:31:42Z", "retentionUntil": "2026-10-28T17:31:42Z", "recordUrl": "https://console.obligra.ai/records/dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "retrievalKeys": { "encounterId": "enc-84721", "patientVisitId": "visit-39281", "generatedSummaryId": "sum-77129", "workflowId": "wf-clinical-summary-v1" } } ``` What each response field means: - **decisionRecordId** — The unique ID of the retained decision record. Store this in your application if your workflow needs to link back to the record. - **status** — Indicates that the request was accepted. 'recorded' means a retained decision record was created. - **verificationState** — The verification state of the record at capture time. 'verifiable' means the record was created with enough integrity evidence to be checked later. - **workflowId** — Echoes back the workflow ID submitted in the request. - **environment** — Echoes back the environment the record was created in. - **createdAt** — Timestamp of when the record was captured (ISO 8601, UTC). - **retentionUntil** — The retention deadline for this record under the current environment policy. - **recordUrl** — A direct link to the record's detail page in the Verify Console. Useful for support tickets and review hand-offs. - **retrievalKeys** — The operational context fields the record can be retrieved by later, echoed back so it is clear what was stored. Store the `decisionRecordId` if your workflow needs a stable reference back to the Verify record. Otherwise, the operational context fields you sent are enough to find the record again. ## Step 7. Find the record in the Verify Console You can either click the `recordUrl` from the capture receipt or open the Verify Console and search for the record. Both paths land on the same record detail page. To search inside the console: - Open the Verify Console. - Go to Records. - Use the search bar or the filter panel. - Search by decisionRecordId first — that always returns exactly one record. - If you do not have the decisionRecordId, search by workflowId or one operational context field, such as encounterId or claimId. - Open the matching result. The search result list shows: - Record ID - Workflow - Environment - Operational context - Created timestamp - Model provider - Verification state - Review status - Retention until This is the production retrieval path. You are not searching prompts. You are retrieving retained decision records by operational context — the identifiers that already exist in your workflow. > **Checkpoint.** You are ready to continue when the record appears in the Records page and the workflow ID matches your test payload. ## Step 8. Inspect the record detail page Open the record. Inspecting the detail page is how you confirm the integration sent everything you expected. If a field is missing or wrong, this is the cheapest place to catch it. Check that each of the following looks correct: - The workflow ID is the stable name you chose in Step 7. - The environment is sandbox (for the first test). - The operational context fields are present and match the values your workflow submitted. - The model provider and model ID are correct. - The output (or the output reference) is present. - The review status reflects the state your workflow set, for example 'pending'. - The retention date is shown and matches the environment policy you expect. - The verification state is visible. Example record summary in the console: ```text Decision record ID: dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7 Workflow: wf-clinical-summary-v1 Environment: sandbox Created: 2026-05-01T17:31:42Z Retention until: 2026-10-28T17:31:42Z Verification state: verifiable Review status: pending ``` Example operational context block: ```text Encounter ID: enc-84721 Patient visit ID: visit-39281 Generated summary ID: sum-77129 Service: clinical-summary-service Request ID: req-93f72a ``` The console makes it clear what was retained, why the record exists, and how it can be reviewed later. If anything looks wrong, fix the capture call and send a new test record before moving on. ## Step 9. Verify the record From the record detail page, click: ```text Verify record ``` Verification checks whether the retained decision record still matches the integrity evidence associated with the record. You do not need to know how that check works internally — only what the result means. The console returns one of three customer-facing outcomes: Example verification API response: ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "verificationState": "verified", "verifiedAt": "2026-05-01T17:36:09Z" } ``` Verification is part of the retrieval path. You should not need a separate forensic process just to confirm whether a retained record still matches its integrity evidence. If the first test record returns "verified," the integration path is working end to end. > **Checkpoint.** You are ready to continue when the Verify Console shows the record as verified or shows a clear verification result. ## Step 10. Retrieve and verify by API You can also retrieve and verify records through the API. This is useful when another system needs to link to Verify records — for example an internal review queue, a case management system, a compliance workflow, or a customer support tool that shows reviewers a "View record in Verify" link. ### Retrieve a record ```typescript const record = await verify.records.get("dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7"); console.log(record.workflowId); console.log(record.operationalContext); console.log(record.verificationState); ``` ### Verify a record ```typescript const result = await verify.records.verify("dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7"); console.log(result.verificationState); console.log(result.verifiedAt); ``` ### Search records ```typescript const results = await verify.records.search({ workflowId: "wf-clinical-summary-v1", environment: "sandbox", operationalContext: { encounterId: "enc-84721" } }); for (const record of results.items) { console.log(record.decisionRecordId, record.verificationState); } ``` API retrieval is the right path when reviewers do not work directly in the Verify Console. The Console remains available for ad-hoc inspection, while the API path keeps everything inside the customer's existing review tools. ## Step 11. API-only option You do not have to install the SDK to send a record. Calling the Verify API directly is useful when you want to test the path with a single curl command before adding a new dependency to the project, or when the project is in a language without first-class SDK support yet. ```bash curl -X POST https://api.obligra.ai/api/v1/decision-records \ -H "Authorization: Bearer $OBLIGRA_VERIFY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflowId": "wf-clinical-summary-v1", "environment": "sandbox", "operationalContext": { "encounterId": "enc-84721", "patientVisitId": "visit-39281", "generatedSummaryId": "sum-77129" }, "model": { "provider": "anthropic", "modelId": "claude-sonnet-4", "modelVersion": "2026-02-15" }, "prompt": "Summarize the telehealth encounter for the attending clinician...", "response": "Generated visit summary text...", "validationState": "passed", "reviewStatus": "pending" }' ``` Expected response: ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "status": "recorded", "verificationState": "verifiable", "workflowId": "wf-clinical-summary-v1", "environment": "sandbox", "createdAt": "2026-05-01T17:31:42Z", "retentionUntil": "2026-10-28T17:31:42Z", "recordUrl": "https://console.obligra.ai/records/dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7" } ``` ## Step 12. Error handling and retries Errors happen when Verify cannot create the record from the request it received. This may happen because a required field is missing, the API key is invalid, the environment name is wrong, the payload format is invalid, or the service is temporarily unavailable. Verify returns structured errors so your application can decide whether to fix the request, retry later, or escalate. A structured error contains an `errorCode`, a human-readable `message`, and a `retryable` boolean. ### Validation error example ```json { "status": "failed", "errorCode": "missing_required_context", "message": "workflowId and environment are required.", "retryable": false } ``` ### Temporary processing error example ```json { "status": "failed", "errorCode": "temporary_processing_error", "message": "The decision record could not be created at this time.", "retryable": true } ``` ### What retryable means - retryable: false means the same request will fail again unless corrected. Fix the payload and try again. - retryable: true means the request may succeed if tried again after a short delay. Use exponential backoff (for example wait 1s, then 2s, then 4s) and stop retrying after a reasonable number of attempts. ### Common errors and what to do | Error code | What it means | What to check | Retry? | | --- | --- | --- | --- | | missing_required_context | A required field was missing from the request. | Confirm workflowId, environment, operationalContext, model.provider, model.modelId, prompt, and response are all present. | No | | invalid_api_key | The API key is missing, malformed, revoked, or expired. | Confirm OBLIGRA_VERIFY_API_KEY is set, was copied correctly, and has not been revoked in the Console. | No | | environment_not_found | The environment in the request does not exist or does not match the API key. | Confirm the environment name (sandbox, staging, production) and that the API key belongs to that environment. | No | | invalid_payload | A field has an unexpected type or shape. | Confirm field types (strings, objects, arrays) match the SDK or API documentation. Check JSON formatting. | No | | temporary_processing_error | Verify could not process the request right now. | Network or service blip. Retry with exponential backoff. | Yes | | rate_limit_exceeded | The workflow is sending requests faster than the environment allows. | Slow the request rate. Retry after the delay indicated in the response. | Yes | ### Recommended client behavior - Retry only when retryable is true. - Use exponential backoff for retryable failures. - Log the captureRequestId or requestId when provided so failures can be traced. - Do not retry validation errors without correcting the payload. - Do not drop failed captures silently. Surface them in your application logs or operational alerting system. ## Step 13. Prevent duplicate records when retrying If a request times out, your workflow may not know whether Verify received it. Many systems automatically retry after a timeout or worker restart. Without a retry key, the same workflow event could create more than one retained decision record. A retry key tells Verify that repeated attempts belong to the same workflow event. The first attempt creates the record; later attempts that carry the same retry key return the same record instead of creating a new one. This is sometimes called idempotency. ### How to choose a retry key Build the retry key from values that are stable for the business event — typically a combination of workflow ID plus one or more operational identifiers (encounter ID, claim ID, transaction ID, case ID). Example retry key: ```text clinical-summary-enc-84721-visit-39281-v1 ``` ### Example using the SDK ```typescript const receipt = await verify.records.create( { workflowId: "wf-clinical-summary-v1", environment: "production", operationalContext: { encounterId: "enc-84721", patientVisitId: "visit-39281" }, model: { provider: "anthropic", modelId: "claude-sonnet-4" }, output: { type: "text", value: "Generated visit summary text..." } }, { idempotencyKey: "clinical-summary-enc-84721-visit-39281-v1" } ); ``` ### What not to do - Do not generate a random retry key for each retry. That defeats the purpose — Verify will see each attempt as a new workflow event and create duplicates. - Do not use a request ID that changes between retries. Use a value tied to the business event, not to the HTTP request. - Do not omit the retry key on retry-prone paths (queue consumers, async workers, scheduled jobs). Use a retry key whenever the same workflow event might be retried because of a network failure, timeout, queue replay, or worker restart. ## Step 14. Production readiness checklist Use this checklist before enabling production capture. It is grouped so different roles can sign off on the parts they own. ### Access and setup - Workspace created - Production environment created - Production API key generated and stored in the approved secret store - Sandbox keys are separate from production keys ### Integration - Verify SDK installed server-side - Verify client initialized once at application startup and reused across requests - Workflow ID defined and stable - Operational context fields selected and consistent across records ### Data handling - Sensitive-data handling reviewed by the data owner - Retention period reviewed and documented - References (inputRef) used in place of raw sensitive content where possible ### Reliability - Error handling implemented (retryable vs non-retryable handled separately) - Retry behavior implemented with exponential backoff - Retry key strategy defined and used on retry-prone paths - Failed captures surfaced in application logs or alerting ### Console validation - First sandbox record captured - Sandbox record retrieved in the Console - Sandbox record verified successfully - Production capture tested with a controlled record ### Approval - Security review completed (or sign-off recorded if not required) - Network/firewall change approved if outbound rules were updated - Implementation lead sign-off recorded - Architect or technical owner sign-off recorded Do not move production workloads to Verify until the capture, retrieval, and verification path has been tested end to end in sandbox and at least one controlled production record has been confirmed. ## Step 15. Common FAQs and troubleshooting The questions below cover the issues most teams hit during a first integration. If you are stuck, scan this list before opening a support ticket — most first-test problems are in here. - **I created an API key. Why can’t I see it again?** — API keys are shown one time, immediately after creation, for security. If the key was not copied, you cannot view it again. Create a new key in the Verify Console and store it in your secret manager right away. - **Can I call Verify from a browser or mobile app?** — No for production use. The API key would be exposed to anyone using the app. Always call Verify from a server-side workflow — a backend service, worker, job, or API route. - **What should I use as workflowId?** — Use a stable name for the business process, not a unique value per record. The same workflow that runs many times a day should produce many records that all share the same workflow ID. Each individual record is identified by its decisionRecordId and operational context. - **What is operational context?** — The business identifiers that let someone find the record later — for example encounter ID, claim ID, transaction ID, case ID, or workflow ID. Use the identifiers your review team would already use to look the record up. - **Should I send the full prompt and full source data?** — Only if approved by the customer's data handling and retention policy. References are usually better — send a stable s3:// URI or internal record ID through inputRef and keep the raw content in the customer system. - **What does "verificationState: verifiable" mean?** — It means the record was created with enough integrity evidence to be checked later. Running verification later returns a clear verified / not verified / verification unavailable result. - **What if I do not see my record in the Console?** — Check, in this order: (1) the API call returned status 'recorded', (2) the environment in the request matches the environment of the API key, (3) the decisionRecordId from the receipt is the one you are searching for, (4) the workflowId is what you expected, and (5) the timestamp is recent. Most missing-record problems are environment mismatches. - **What if the API request fails?** — Read errorCode and retryable. If retryable is false, fix the payload (most often a missing required field or a wrong environment name) before retrying. If retryable is true, retry with exponential backoff and stop after a reasonable number of attempts. - **What if my workflow sends the same record twice?** — Use a retry key built from the business event (for example workflow ID plus encounter ID or claim ID). Verify treats repeated attempts with the same retry key as the same workflow event and does not create duplicate records. - **When should I move from sandbox to production?** — Only after the test record can be captured, retrieved, inspected, and verified end to end in sandbox, and the production readiness checklist is complete. Moving early creates production records that may not match your retention or review expectations. - **Do we need to change model providers?** — No. Verify does not require changing the model provider for this guide. The integration runs alongside whichever model your workflow already uses. - **Does Verify replace our source system?** — No. Verify retains decision records that reference operational context from the customer workflow. The source system (electronic health record, claims system, ledger, case manager) remains the source of truth for the business event. For deeper coverage organized by symptom — SDK installation, environment variables, API keys, payload fields, records not visible in the Console, AWS account deployment, CloudFormation, Terraform, capture policy, search and retrieval, verification, and when to contact support — see [Troubleshooting Verify Integrations](/resources/troubleshooting-verify-integrations) . --- --- title: Install and Configure Verify slug: install-and-configure-verify category: Developers retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/install-and-configure-verify canonicalUrl: "https://obligra.ai/resources/install-and-configure-verify" llmTags: - llm-aligned - integration - implementation-guide - setup-readiness - developer-enablement - retrieval-tier-3 - supporting-reference --- # Install and Configure Verify _Developers_ _Most first-time Verify integrations succeed when the team treats the install as a Sandbox-first validation loop rather than a configuration checklist. This guide is shaped around that loop: get Sandbox ready, place credentials where the secret-management program expects them, install the SDK or wire up direct HTTP, capture a first record from a trusted server-side runtime, retrieve it by operational context, inspect it, verify it, and only then plan the cutover to Production. In practice, every Production rollout that lands cleanly traces back to a clean Sandbox loop completed end-to-end first._ ## Overview Obligra Verify captures retained decision records from AI-assisted operational workflows so customer teams can retrieve, inspect, and verify them later. In plain customer language: - Verify captures retained decision records — review-ready evidence associated with an AI-assisted workflow. - Each retained decision record preserves the workflow evidence customer teams need later — for operational, compliance, audit, quality, fraud, legal, or review work. - Verify is retrieval-oriented. Records are retrieved later by the operational identifiers customer teams already use day-to-day — claim, encounter, transaction, escalation, policy, or workflow reference. - Verify supports AI-assisted operational workflows. It does not replace customer workflow systems and does not sit in the live AI inference path. - Verify supports review-oriented operational accountability across claims, compliance, audit, quality, fraud, legal, and operations teams. > Most customers should begin by validating one Sandbox workflow end-to-end before Production rollout. > > > > > One workflow captured, retrieved, inspected, and verified in Sandbox is a faster path to a confident Production rollout than expanding the integration first. ## What you need before starting The following requirements should be in place before installing or configuring Verify in a customer environment. | Requirement | Why it matters | | --- | --- | | Verify account access | Required for Console and API access. The Console is where API keys are created and where activity and usage are reviewed. | | Sandbox environment | Safe onboarding and validation environment. Sandbox is intended for non-production usage and end-to-end integration testing. | | Backend service or workflow runtime | Verify capture should be server-side. A trusted backend service or workflow runtime is required to hold the API key and submit retained decision records. | | AI-assisted workflow | The source of retained workflow evidence. Verify is captured after an AI-assisted workflow produces an output — there must be an output to capture. | | Stable operational identifiers | Required for retrieval-oriented workflows. Customers attach business identifiers (claimId, encounterId, transactionId, escalationId, policyId) to each record so operators can retrieve records later by information they already use. | - Verify capture should occur after the AI-assisted output exists — capture preserves the output as part of the retained decision record. - Verify is not a replacement for customer workflow systems. It is a separate system of record for AI-assisted decisions, captured alongside the workflow. - Verify preserves review-ready workflow evidence — not generic application logs or telemetry. ## Recommended architecture pattern Verify is designed to be called from trusted server-side environments. The recommended integration topology is: ```text User or Internal Workflow → Customer Application → Customer Backend or Workflow Service → AI Workflow Produces Output → Verify Capture API ``` - Verify API keys belong in the customer backend or workflow service — not in source code, not in frontend bundles, not in mobile binaries. - Frontend and mobile applications should call the customer backend, not the Verify API directly. - The customer backend attaches operational context (claimId, encounterId, transactionId, escalationId, policyId, etc.) and submits the retained decision record from a trusted runtime. - Records should be captured after the AI-assisted workflow produces output — so the output, the surrounding workflow context, and the operational identifiers are all preserved together. > Verify APIs are intended for trusted server-side environments only. > > > > > The capture surface is not designed for browser-side JavaScript, mobile clients, embedded devices, or any other untrusted runtime. ## Direct vs governed deployments Both deployment models are supported. The diagrams below show where capture and field retention policy evaluation happens in each one. ### Direct integration ```text Customer Backend │ ▼ Verify API ``` - Builder onboarding - Sandbox - Evaluation - Internal testing ### Governed integration ```text Customer Backend │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy │ ▼ Field Retention Policy │ ▼ Verify API ``` - Production - Governance - Enterprise - Regulated workloads > The Verify API is the same endpoint in both patterns. The customer-owned proxy is a customer-side component that evaluates capture decisions and field retention before any data is forwarded to Verify. ## Customer-owned proxy and capture policies In governed deployments, two independent governance layers run inside the customer-owned proxy before any data is transmitted to Verify: - Capture decision policy — determines whether the record should be retained. Outcomes are binary: capture or skip. - Field retention policy — determines which fields are permitted to leave the customer account. Outcomes are per-field: allow, drop, redact, truncate, or neverForward. Both evaluations occur inside the customer-owned proxy before any data is transmitted to Verify. Verify receives only approved fields. > Verify does not determine what customer data is captured. The customer-owned proxy determines whether a record is retained and which fields are forwarded. Verify is not a surveillance logger — it receives only what the customer chooses to forward. For the policy contract, file shape, evaluation order, and field retention outcomes, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## Which deployment model should I choose? Pick the deployment model that matches the workload being integrated. Both patterns reach the same Verify API. | Scenario | Recommended pattern | | --- | --- | | First evaluation | Direct SDK | | Sandbox testing | Direct SDK | | Internal tools | Direct SDK | | Production workloads | Customer-owned proxy | | Governance | Customer-owned proxy | | Enterprise | Customer-owned proxy | | Regulated workloads | Customer-owned proxy | ## Step 1 — Sign into Verify The first integration step is reaching the Verify Console from your customer account. - Sign into the Verify Console using your customer credentials. - Confirm workspace visibility — the workspace you intend to integrate against should be selected. - Confirm a Sandbox environment exists for the workspace. If it does not, Sandbox should be provisioned before any API key creation. - Review onboarding status from the Console — outstanding setup items should be addressed before capture. - Review environment separation — confirm Sandbox and Production are clearly distinct in the Console UI before generating any credentials. ### What Sandbox is for - Onboarding — first-time customer team integration walk-through. - Testing — integration tests, regression tests, and customer-side smoke tests. - Workflow validation — end-to-end capture, retrieval, inspection, and verification dry runs. - Non-production operational review — reviewers can practice the retrieval workflow before it matters in Production. [Open the Interactive Sandbox →](/sandbox) ## Step 2 — Create your first API key API keys are the credentials your customer backend uses to submit retained decision records. The first key should be created against Sandbox. - Navigate to API Keys in the Verify Console. - Confirm the active environment is Sandbox before creating the key. - Create a Sandbox API key. - Choose an operationally meaningful name — something a future operator will recognize months later. - Copy the raw API key immediately and store it in a secret manager. The raw key is shown once, at creation. ### Naming guidance - **Good** — Sandbox Claims Review · Telehealth Intake Capture · Fraud Workflow Sandbox · Sandbox Underwriting Triage - **Avoid** — temp · key1 · test123 · placeholder · key-2025-05-18 > API keys are shown only once. > > > > > If a key is lost, rotate it and create a new one — there is no way to retrieve the raw key after creation. ## Step 3 — Store the API key securely The API key is a long-lived credential. Treat it like a database password — its handling determines the security posture of the whole integration. ### Recommended storage - Environment variables injected into the backend service at runtime. - Cloud secret managers — AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, or equivalent. - CI/CD secret stores for build-time injection — GitHub Actions secrets, GitLab CI variables, CircleCI contexts, or equivalent. ### Explicitly discouraged - Frontend JavaScript bundles or single-page applications. - Mobile applications or embedded clients. - Screenshots shared in chat, tickets, or documentation. - Source control — even private repositories. - Plaintext configuration files committed to any artifact store. - Application log lines or APM events. > Do not expose Verify API keys in browser applications or public repositories. > > > > > If a key is suspected to be exposed, rotate it immediately and review the records captured during the exposure window. ## Step 4 — Install the SDK or use HTTP APIs Customers can integrate Verify using an official SDK or by calling the HTTP APIs directly. Both approaches submit the same retained decision records — the choice depends on customer-side preferences. - SDKs simplify integration workflows — client configuration, request shaping, retry plumbing, and idempotency handling are wrapped behind a stable surface. - HTTP APIs provide direct control — useful when an SDK is not available for the customer's runtime, or when the customer team prefers explicit request handling. ### Install (Node.js) ```bash npm install @obligra/verify-sdk ``` ### Install (Python) ```bash pip install obligra-verify ``` Language and runtime availability may vary depending on current SDK support. Confirm SDK availability for the target runtime from the Verify Console or the SDK Reference before standardizing on a specific package. ## Step 5 — Create your first capture payload The capture payload is the customer-visible body of a retained decision record. A first integration should include the fields below. | Field | Required | Purpose | | --- | --- | --- | | workflowId | Yes | Identifies the operational workflow that created the record. | | operationalContext | Yes | Supports retrieval later. Contains the business identifiers operators already use day-to-day. | | model.provider | Yes | Identifies the model provider used by the AI-assisted workflow. | | model.modelId | Yes | Identifies the model used by the workflow. | | aiAssistedContext | Optional | Captures prompt, response, or surrounding workflow context when available. Uses the canonical prompt/response capture model. | ### Example payload ```json { "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214" }, "model": { "provider": "anthropic", "modelId": "claude-3-5-sonnet" }, "aiAssistedContext": { "prompt": "Summarize the claim.", "response": "Potential escalation indicators detected." } } ``` - Use stable business identifiers operators already use — not transient request IDs or generated tokens. - Avoid temporary test values (CLM-TEST-1, FAKE-123, placeholder strings) in Production payloads. - Choose identifiers operators can recognize and retrieve months later — claim, policy, encounter, transaction, escalation, or case references. ## Step 6 — Submit your first record The illustrative request below shows the shape of a first-time capture call from a customer backend. Replace `` with the Sandbox API key created in Step 2. ```bash curl -X POST "https://api.obligra.ai/api/v1/decision-records" \ -H "Content-Type: application/json" \ -H "X-Verify-Api-Key: " \ -d '{ "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214" }, "model": { "provider": "anthropic", "modelId": "claude-3-5-sonnet" }, "aiAssistedContext": { "prompt": "Summarize the claim.", "response": "Potential escalation indicators detected." } }' ``` ### What success looks like - A successful capture creates a retained decision record in Sandbox. - The response includes a decisionRecordId — useful for direct inspection and verification calls later. - Retrieval keys derived from operationalContext help operators retrieve the record later by information they already know. - verificationState may begin as not_verified and transition when verification is run. ### Example response ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "status": "recorded", "verificationState": "not_verified", "workflowId": "claims-review", "environment": "sandbox", "createdAt": "2026-05-18T14:30:00.000Z", "retentionUntil": "2026-05-25T14:30:00.000Z", "retrievalKeys": ["CLM-220145", "POL-99214"] } ``` The host shown above is illustrative. Use the host configured for your Verify environment from the Verify Console. ## Step 7 — Retrieve the record > Retrieval is operational-context-first. Start with what you know. > > > > > Operators retrieve retained decision records using information they already have — not internal record IDs or generated tokens. Common operational identifiers for retrieval include: - claimId - encounterId - transactionId - escalationId - policyId - workflowId - date range ```bash curl -H "Authorization: Bearer " \ "https://api.obligra.ai/api/v1/decision-records?retrievalKey=CLM-220145" ``` - Wrong environment is the single most common reason records appear missing during a first integration. Confirm the active environment before assuming a record was not captured. - Retrieval workflows are environment-aware — a Sandbox retrieval call will not return Production records, and vice versa. ## Step 8 — Inspect the record Inspection returns the customer-visible fields of a single retained decision record. Operators use inspection to confirm: - workflow identifier — which workflow produced the record - operational context — the business identifiers attached at capture - prompts and responses — the AI-assisted context preserved with the record - chronology-oriented timestamps — when the record was created and how long it is retained for review - verification status — the current review-oriented verification state ```bash curl -H "Authorization: Bearer " \ "https://api.obligra.ai/api/v1/decision-records/dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7" ``` Retained records are intended to support review-oriented operational workflows — claims, compliance, audit, quality, fraud, legal, and operations review. ## Step 9 — Verify the record Verification produces a review-oriented signal on a retained decision record without modifying the record itself. - Verification is review-oriented — it produces a review-time signal for reviewers. - Verification is non-destructive — it does not modify the retained record. - Verification is safe to repeat — repeated calls produce consistent customer-visible state. - Verification is intended for operational review across claims, compliance, audit, quality, fraud, legal, and operations teams. ### Example request ```bash curl -X POST \ -H "Authorization: Bearer " \ "https://api.obligra.ai/api/v1/decision-records/dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7/verify" ``` ### Example response ```json { "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7", "verificationState": "verified", "verifiedAt": "2026-05-18T15:00:00.000Z", "resultSummary": "Record integrity was verified." } ``` ### Verification states - **verified** — The retained record passed its review-time verification check at the time of the call. - **not_verified** — Verification has not yet been run on this retained record. - **failed** — Verification was run and did not return a confirming result. Operators should investigate using the customer-visible record fields. ## How to know installation worked Use this checklist to confirm the installation and the first integration are wired end-to-end: - API key created — a Sandbox API key is visible in the Verify Console and stored in the customer secret store. - SDK or API configured — the customer backend has the API key, base URL, and any required client settings loaded at runtime. - Capture request succeeds — the call returns without network or SDK errors. - decisionRecordId returned in the capture response in the dr_ format. - Record appears in the Verify Console under the active environment and workspace. - Retrieval works — the record can be found by decisionRecordId and by operational context. - Verification succeeds — calling verification returns a verification result. - Activity history visible — capture, retrieval, and verification events are listed for the record. - Environment separation confirmed — Sandbox and Production are isolated end-to-end. > If every item above is true, the installation is working correctly. Continue to the Production readiness checklist before promoting any workflow to Production. ## Common setup problems A handful of issues account for most first-integration friction. If something is not behaving as expected, see [Troubleshooting Verify Integrations](/resources/troubleshooting-verify-integrations) for symptom-first coverage. - Invalid API key — usually a wrong-environment key, a revoked key, or whitespace pasted into the value. - Wrong environment — capturing in Sandbox while searching Production, or vice versa. - Record not visible — capture appeared to succeed but the record cannot be found in the Console. - Capture policy skipped record — in customer-owned proxy deployments, a skip rule may have matched. - Wrong AWS account — Terraform or CloudFormation deployed the customer-owned proxy into an unintended AWS account. - Verification unavailable — verifying a Sandbox record with a Production credential, or vice versa. ## Sandbox vs Production Verify enforces strict environment separation. Sandbox and Production are independent — separate API keys, separate records, separate retrieval surfaces, separate operational dashboards. - Sandbox is intended for onboarding and validation — not for live operational evidence. - Production is intended for live operational workflows whose retained decision records will be retrieved, reviewed, and verified by downstream teams. - Records do not move between environments. A Sandbox record cannot be retrieved from Production. - API keys are environment-aware. Sandbox keys are not valid in Production, and vice versa. - Customers should validate the full capture-and-retrieve loop in Sandbox before promoting any workflow to Production. > Do not use Sandbox records as Production evidence. > > > > > Confirm the active environment before review, escalation, or any downstream operational action. ## Retry and rate-limit guidance Capture and retrieval calls should be retry-aware. The customer backend is responsible for bounded retries and backoff on retry-prone paths. - Use bounded retries — a small attempt count for synchronous paths, a slightly larger bound for async workers. - Use exponential backoff with jitter between attempts. - Avoid duplicate workflow submissions — preserve a stable retry key tied to the business event, not the HTTP request. - Preserve operational context (claimId, encounterId, transactionId, escalationId, workflowId) across every retry attempt. - If the capture status is uncertain after a timeout, retrieve by operational context before resubmitting. - If retrieval shows the record was already recorded, do not retry the capture call. ### Handling 429 (rate limited or usage limit reached) - Wait before retrying — respect a backoff rather than retrying immediately. - Reduce concurrency on the customer side until the rate limit clears. - Review plan and usage from the Verify Console if 429s persist beyond a transient burst. Exact retry windows and rate-limit semantics may vary by configuration and the active published API contract. Customer workflows should not depend on specific retry timing beyond what the active contract documents. ## Common first-time mistakes The following pitfalls are the most common operational issues new integrators encounter. Reviewing them before Sandbox rollout reduces friction during Production rollout. | Mistake | How to avoid it | | --- | --- | | Frontend API-key usage | Keep capture server-side. Frontend and mobile applications should call the customer backend, which submits to Verify on their behalf. | | Sandbox / Production crossover | Separate environments clearly — separate API keys, separate dashboards, separate downstream review surfaces. Confirm the active environment before any capture or retrieval call. | | Missing operationalContext | Always include stable business identifiers like claimId, encounterId, transactionId, or escalationId — the values reviewers will actually use to retrieve the record later. | | Weak workflowId values | Use meaningful, stable workflow names like claims-review or fraud-triage. Avoid build artifacts, generated tokens, or values that change between releases. | | Logging credentials | Redact API keys and bearer tokens from application logs, APM events, and error trackers before they ship to log infrastructure. | | Retry storms | Use bounded retries with exponential backoff and jitter. Preserve operational context across attempts and rely on retry keys for de-duplication. | | Treating retained records as generic logs | Review retained decision records as workflow evidence — for operational, compliance, audit, quality, or legal review — not as generic application logs. | ## Production readiness checklist ### Before Production Before opening Production rollout, confirm the following. Each item below is a gate, not a suggestion. - Sandbox validation complete — capture, retrieval, inspection, and verification all succeed end-to-end in Sandbox. - Capture policy reviewed — in governed deployments, the capture decision policy and the field retention policy have been reviewed and signed off by the customer team that owns the policy. - Operational identifiers finalized — the workflowId and operational context values are stable and meaningful for reviewers. - API keys stored securely — keys are loaded from the customer secret store at runtime, not from source control. - Retrieval workflows tested — reviewers can find captured records by the business identifiers they actually use. - Verification tested — calling verification on captured records returns expected results. - Troubleshooting guide reviewed — the team has a shared understanding of how to diagnose first-line issues. ### Production readiness checklist Before promoting a workflow from Sandbox to Production, the following should all be true. This checklist closes the common gaps customer teams discover late. - Sandbox capture succeeds — a retained decision record is recorded from the customer backend. - Retrieval works by operational context using the same identifiers reviewers will use day-to-day. - Verification works end-to-end — calling verification on a captured record returns a verification result. - API keys are stored securely in a secret manager — not in source control, frontend bundles, or mobile binaries. - Retries are bounded, backoff-aware, and idempotent — duplicate records are prevented across retries. - Operational identifiers are stable — workflowId and operationalContext values reviewers will actually recognize. - Sandbox and Production are separated — distinct API keys, distinct downstream review surfaces, distinct operational dashboards. - Workflow chronology is visible — operators can confirm when records were created and retained until. - Onboarding procedures are documented — internal runbook describes how new team members will integrate, retrieve, and verify. - Operators understand retrieval workflows — claims, compliance, fraud, legal, or operations reviewers know how to retrieve records using operational context. ## Related documentation Pair this guide with the following resources for the full first-integration picture: - [API Reference — first-time-user API reference with the full capture, retrieval, inspection, verification, error, and Production readiness picture.](/resources/api-reference) - [SDK Reference — capture SDK methods, environment-aware onboarding, and operational context guidance.](/resources/verify-sdk-reference) - [Configuring an AI Capture Policy — capture decision policy and field retention policy for customer-owned proxy deployments.](/resources/configuring-an-ai-capture-policy) - [Troubleshooting Verify Integrations — symptom-first reference for SDK, API, Terraform, CloudFormation, capture policy, and Console issues.](/resources/troubleshooting-verify-integrations) - [Customer Integration Patterns — AWS Lambda, container/ECS, queue-based capture, and webhook delivery patterns.](/resources/customer-integration-patterns) - [Reference Architecture: AWS — customer-side reference deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) - [Webhook Events — server-to-server notifications about selected retained decision record activity.](/resources/webhooks) - [Customer Security Overview — broader customer-side security posture around Verify integrations.](/resources/security-overview) - [Using AI Assistants with Verify — how AI-assisted workflows fit alongside Verify capture.](/resources/using-ai-assistants-with-verify) - [Retry and idempotency — capture-side retry and idempotency behavior referenced from this guide.](/resources/verify-sdk-reference#safe-retry-behavior) - [What Is Obligra Verify — product positioning and capabilities overview.](/resources/what-is-verify) --- --- title: Introduction to Obligra Verify slug: introduction-to-verify category: Fundamentals retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/introduction-to-verify canonicalUrl: "https://obligra.ai/resources/introduction-to-verify" llmTags: - llm-aligned - canonical-concept - system-of-record - retrieval-tier-3 - supporting-reference --- # Introduction to Obligra Verify _Introduction_ _Turn AI-assisted decisions into retained, reviewable, and verifiable records._ ## Summary Obligra Verify is a system of record for AI-assisted decisions. It captures AI-assisted decisions as they happen and preserves them as structured decision records that can be retrieved, reviewed, and verified later. Verify is built for workflows where AI-generated or AI-assisted outputs influence real business activity, such as clinical summaries, transaction reviews, claim assessments, risk classifications, customer communications, or operational routing. Most systems can generate AI outputs. Very few can preserve those outputs as retained, reviewable, and verifiable decision records. Verify closes that gap. ## 01. What is Verify? Obligra Verify is a decision record layer for AI-assisted workflows. It works alongside your existing applications, models, cloud services, workflow engines, and logging tools. It does not replace them. When an AI-assisted workflow produces an output, Verify captures the decision state around that output and stores it as a structured decision record. A decision record can include: - the input provided to the system - the context retrieved at runtime - the prompt or request structure - the model execution metadata - the generated output - validation and policy results - operational identifiers such as claim ID, encounter ID, transaction ID, workflow ID, or case ID - integrity and retention metadata The purpose of Verify is not to generate more AI outputs. The purpose is to preserve the decision record after an AI-assisted output affects a workflow. That distinction matters. A model may generate a response. A workflow may use that response. A downstream system may continue operating. But if the organization cannot later retrieve what happened, what context existed, what output was produced, and whether the retained record still verifies, the organization has a record problem. Verify solves that record problem. ## 02. Why Verify exists AI systems are increasingly being used inside operational workflows, not just experiments or internal prototypes. They summarize clinical encounters. They support transaction review. They help classify risk. They draft customer communications. They assist with claims, coverage, intake, routing, and review. That creates a new record problem. The moment an AI-assisted output influences a workflow, the organization may later need to explain what happened. A clinical summary may be questioned. A transaction review may be disputed. A claim recommendation may be challenged. A compliance team may ask which controls were applied. An auditor may need evidence that the retained record has not changed. Most systems are not designed for that moment. They may have logs, traces, dashboards, screenshots, exports, tickets, notes, and fragments. Those artifacts may help engineers investigate system activity, but they do not necessarily preserve the decision itself. The problem is not generation. The problem is persistence. Organizations can generate AI outputs, but many cannot reliably produce the retained decision record later. That is the post-inference record gap. Verify exists because teams should not be reconstructing AI-assisted decisions after the fact. They should be retrieving them. ## 03. The value Verify provides Verify adds value by making AI-assisted decisions easier to retain, retrieve, review, and verify. For engineering teams, Verify provides a consistent decision record structure across workflows, models, and providers. Teams do not need to design a custom evidence model for every AI use case. For architects, Verify creates a stable record layer between AI execution and later review. The model can change. The workflow can evolve. The decision record structure remains consistent. For product teams, Verify supports a safer path to production because reviewability is not treated as an afterthought. For compliance, legal, audit, and risk teams, Verify provides retained decision evidence that can be inspected later. For business teams, Verify reduces the cost and uncertainty of investigations. Instead of asking multiple teams to rebuild what happened, the organization starts from the preserved record. That is the customer value. Verify does not simply store data. Verify preserves the decision record that gives teams something concrete to retrieve when questions arise. ## 04. The problem with relying on logs Logs are useful. They help teams debug systems, monitor runtime behavior, and investigate application or infrastructure issues. But logs are not decision records. A log may show that a request was received. It may show that a model endpoint was called. It may show that a workflow advanced. It may include timestamps, request IDs, service names, or partial payloads. That does not mean the organization has preserved the AI-assisted decision. A complete decision may depend on: - what input entered the workflow - what context was retrieved - what prompt or instruction set was used - which model and parameters produced the output - what output was generated - what validation checks or review flags applied - what business workflow the output belonged to - whether the retained record can still be verified Logs usually capture activity. Verify preserves decision evidence. This distinction matters when the question changes from: “Did the system run?” to: “What decision was produced, what context surrounded it, and can we verify the retained record?” Logs show pieces of the event. Verify preserves the record of the decision. ## 05. Why reconstruction is not a strategy Reconstruction means trying to rebuild a decision after it happened. That usually requires teams to search logs, inspect workflow systems, rebuild prompts, re-query data sources, compare exports, check tickets, and ask engineers or operators to piece together what likely occurred. In AI-assisted workflows, that approach is weak. Prompt templates may have changed. Model versions may have changed. Retrieved context may have changed. External data may have changed. Validation logic may have changed. Logs may be incomplete, expired, sampled, or spread across systems. Even if a team produces a reasonable explanation, the organization may still not have the original decision record. A reconstructed decision is an approximation. A retained decision record is evidence. Verify shifts the operating model from reconstruction to retrieval. ## 06. How Verify works Verify integrates where AI-assisted decisions are produced. When a workflow generates an AI-assisted output, Verify captures the decision state and stores it as a structured record. That record can include: what the system received what data was retrieved or referenced how the model or AI component was instructed provider, model, version, parameters, request metadata the exact generated result checks, policy outcomes, review flags, escalation triggers workflow ID, case ID, encounter ID, transaction ID, service name, environment integrity reference, retained-at timestamp, verification status retention policy, retention window, lifecycle state Once stored, the record can be retrieved using operational context. That is important because real teams do not usually search historical AI activity by remembering the exact prompt. They search by the business identifiers they already have. Examples: - Find the AI-assisted summary for this patient encounter. - Retrieve the decision record for this claim. - Show transaction reviews from this date range. - Find decisions generated by this workflow. - Show records that triggered manual review. - Verify that this retained record has not changed. Verify makes those records available without requiring teams to rebuild the decision from logs and fragments. ![End-to-End Decision Record Lifecycle with Obligra Verify. A six-stage horizontal flow showing the lifetime of a retained decision record: AI-assisted workflow runs in the customer runtime, decision context is captured at the customer-owned capture boundary by the Verify SDK, submitted to Verify through the customer-owned proxy after the Capture Decision Policy and Field Retention Policy approve which fields may leave the customer environment, retained as one decision record indexed by operational context on the Obligra managed platform, retrieved and verified by a reviewer using the operational identifier the customer team already uses, and reviewed by the customer audit, compliance, legal, risk, or operations team. The bottom band shows which zone each stage runs in. Bottom callout: Captured once at execution time. Reviewed many times across the lifetime of the record.](/diagrams/obligra-verify-end-to-end-decision-record-lifecycle.svg) *Obligra Verify captures the decision state at the point where AI-assisted outputs are produced. The retained record can be retrieved, reviewed, and verified later without reconstructing the workflow from logs and fragments.* ## 07. What makes Verify different Verify is not: - observability - monitoring - logging - telemetry - prompt tooling - model evaluation - inference optimization - a dashboard for AI systems - a generic responsible AI platform Those tools serve different purposes. Verify focuses on retained decision evidence. | Existing approach | Limitation | Verify model | | --- | --- | --- | | Logs and traces | Show system activity, not full decision state | Preserves complete decision records | | Screenshots and exports | Manual, inconsistent, hard to verify | Captures structured records at execution | | Model provider history | Provider-specific and often incomplete | Creates model-agnostic decision records | | Workflow state | Shows process status, not full AI context | Links decisions to operational context | | Reconstruction | Slow, incomplete, dependent on current system state | Enables direct retrieval of decision evidence | The difference is operational. Without Verify, teams ask: “Can we figure out what happened?” With Verify, teams ask: “Can we retrieve the decision record?” That is a better operating model. ## 08. Where Verify adds value Verify is most valuable in workflows where AI-assisted outputs may later be questioned, reviewed, audited, or disputed. The initial verticals are: - healthcare - banking and financial services - insurance These are not three disconnected markets. They are one pattern in three high-risk domains. Across all three, AI-assisted workflows produce outputs that may influence real decisions. Those decisions may need to be retrieved, reviewed, and verified later. The industries are different. The record problem is the same. ![Three industry cards arranged horizontally with arrows feeding into a single Verify decision record layer underneath: Healthcare and Telehealth, Banking and Financial Services, and Insurance. Each industry card carries a one-line description of where AI assists the workflow. Bottom takeaway: Different industries. Different reviewers. The same record problem.](/diagrams/obligra-verify-three-industries-one-record-problem.svg) *Different industries. Different reviewers. The same record problem.* | Industry | Reviewers who arrive later | | --- | --- | | Healthcare & Telehealth | Clinical quality review · malpractice review · payer audit · regulator inquiry · patient access request | | Banking & Financial Services | Transaction dispute · fraud and AML review · regulator inquiry · internal compliance audit · legal hold and litigation | | Insurance | Claims appeal review · regulator inquiry · reinsurance review · fraud investigation · litigation discovery | ## 09. Healthcare Healthcare organizations are using AI across documentation, intake, triage, summaries, follow-up instructions, prior authorization support, and clinical operations workflows. When an AI-assisted output influences a care workflow, the organization needs more than a log entry. It needs a retained decision record tied to the encounter, workflow, output, and review context. Example use cases include: - telehealth intake summaries - clinical note generation - triage and escalation support - patient follow-up instructions - care plan summaries - prior authorization support - nurse review workflows - provider-facing AI recommendations When a clinical summary, patient-facing response, or virtual-care interaction is questioned later, the organization needs to retrieve what happened. That means knowing what was generated, what workflow produced it, what context existed, what controls applied, and whether the retained record still verifies. Verify helps healthcare teams preserve the decision record for later review. AI-assisted care workflows need retained, review-ready records. ## 10. Banking and financial services Banks, fintechs, lenders, payment companies, and financial services firms are using AI across fraud review, transaction monitoring, underwriting support, customer support, dispute handling, risk review, and operational workflows. When a transaction, customer interaction, or risk workflow is challenged later, the organization needs to retrieve the preserved record of what the system produced and what context surrounded it. Example use cases include: - fraud review support - transaction dispute review - risk classification - underwriting assistance - credit decision support - customer support response drafting - suspicious activity workflow support - compliance review workflows Financial workflows need more than activity records. They need retained decision evidence that can be retrieved and reviewed later. Verify gives financial teams a record tied to the transaction, account, workflow, model path, output, review state, and verification result. That reduces ambiguity when decisions are questioned. ## 11. Insurance Insurance organizations are using AI across claims intake, coverage review, eligibility support, underwriting assistance, loss summarization, customer communication, and risk classification workflows. When an AI-assisted recommendation affects a claim, coverage path, or customer communication, the organization needs a preserved record that can be reviewed later. Example use cases include: - claims intake summaries - coverage review support - underwriting assistance - risk classification - eligibility support - customer communication drafting - fraud indicators and claim review - appeals and dispute review When AI helps shape coverage, claims, or risk workflows, the record matters. If the workflow is challenged later, the organization needs to retrieve what happened, not guess at it. Verify lets insurance teams retrieve the preserved record tied to the claim, policy, workflow, AI-generated output, and verification state. ## 12. Three industries. One pattern. Healthcare, banking and financial services, and insurance operate under different rules, risks, and review processes. But the same pattern appears in each industry: AI-assisted workflows are moving into operational decisions. When those workflows are questioned later, teams need to know: - what was generated - what workflow produced it - what business context applied - what controls were in place - whether a human reviewer acted - whether the retained record still verifies That is the shared record problem. Verify is designed for that pattern. AI-assisted workflows need retained records that can be retrieved and verified later. ## 13. Why retrieval matters Retrieval is the operating model Verify enables. Reconstruction asks teams to rebuild a past decision after the fact. Retrieval gives teams access to the retained record of the decision as it happened. This matters because AI-assisted workflows are dynamic. The model may change. The prompt may change. The retrieved context may change. The workflow may change. The business rules may change. If the record was not captured at execution time, the original decision state may never exist again in the same form. Retrieval avoids that problem. It gives teams a durable record they can inspect directly. ## 14. Why verification matters A retained record should not only be visible. It should be verifiable. When a decision record is retrieved, teams may need to know whether the record still matches what was captured at execution time. That is where verification metadata, the integrity reference, and the customer-visible verification status matter. This is especially important when decision records are used for audit, dispute resolution, regulatory review, legal review, or internal governance. The question is not only: “Can we find the record?” The stronger question is: “Can we verify that this retained record has not changed?” Verify is built around retained records that support review and verification. ## 15. Why model-agnostic decision records matter Enterprise AI stacks will not stay fixed. Organizations are already using different models for different workflows. A healthcare team may use one model for documentation support and another for patient communication. A bank may use separate models for fraud review, customer support, and analyst workflows. An insurer may use different providers for claims intake, underwriting support, and customer communication. That pattern will continue. Model providers will change. Internal models will mature. Cloud strategies will shift. Some workflows may run through commercial model APIs. Others may run through Bedrock, Azure, Google, private infrastructure, or on-prem environments. If the record of an AI-assisted decision depends on one model provider’s history, log format, or platform-specific audit trail, the organization inherits a fragile evidence model. That creates risk. A provider migration can break continuity. A workflow can become harder to review after a model change. A compliance team may need to compare decisions across systems that do not preserve records the same way. An audit team may find that decision evidence is stored differently depending on which model produced the output. Verify avoids that problem by separating the decision record from the model provider. The model can change. The workflow can change. The infrastructure can change. The record structure remains consistent. A Verify decision record captures the decision state around the model invocation: input, context, prompt or request structure, model execution metadata, output, validation results, operational identifiers, integrity metadata, and retention metadata. That gives teams a stable system of record for AI-assisted decisions across changing AI infrastructure. The value is not simply provider flexibility. The value is continuity. When AI programs evolve, organizations still need to retrieve, review, and verify decisions made months or years earlier. Model-agnostic decision records make that possible. ![Model-Agnostic Decision Records. A layered visual showing five different inference environments — a direct model API path, a cloud-hosted AI service path, a multi-cloud routing path, a hybrid deployment path, and a private or on-prem model path — all converging on a single Verify decision record layer that preserves the same retained record shape regardless of which inference path produced the output. Bottom callout: The model layer changes. The record layer stays stable.](/diagrams/obligra-verify-one-record-across-deployments.svg) *Verify separates decision evidence from model provider history. Models, clouds, and workflows can change while the retained decision record structure remains consistent for later retrieval, review, and verification.* ## 16. What Verify gives the organization Verify creates value by giving teams a retained record they can use when AI-assisted decisions are questioned. For engineering teams, this means fewer custom audit artifacts and less dependency on scattered logs. Teams can use a consistent structure for capturing decision evidence across workflows, models, and providers. For architects, Verify creates a stable record layer between AI execution and later review. The model layer can change, the workflow can evolve, and the infrastructure can move across cloud or on-prem environments without changing the basic record model. For product teams, Verify supports a safer path to production AI workflows. Reviewability is built into the workflow instead of being added after the first dispute, audit request, or customer escalation. For compliance teams, Verify provides retained decision evidence that can be retrieved, inspected, sampled, and verified. That matters when review depends on evidence rather than explanation. For auditors and legal teams, Verify creates a durable artifact that supports review, dispute analysis, and control testing. For business leaders, Verify reduces uncertainty. When an AI-assisted decision is questioned, the organization does not start from fragments. It starts from the decision record. The value is not only that a record exists. The value is that the record can be retrieved, reviewed, and verified when it matters. ## 17. Get started Start with the core concepts: - Why Retrieval Beats Reconstruction - Structure of a Decision Record - Evidence vs Logs - Retrieval by Operational Context - Verification Lifecycle Then use the sandbox to see how an AI-assisted decision becomes a retained record. The goal is simple: Stop reconstructing decisions after the fact. Start retrieving decision evidence. ## 18. Detailed summary Obligra Verify is a system of record for AI-assisted decisions. It exists because organizations are adopting AI inside workflows where decisions may later need to be reviewed, audited, disputed, or explained. Most AI systems can generate outputs, but they do not automatically preserve the full decision state behind those outputs. Verify captures AI-assisted decisions as retained, reviewable, and verifiable records. Each decision record can preserve the input, context, prompt structure, model execution metadata, output, validation results, operational identifiers, integrity metadata, and retention information needed to review the decision later. The product is model agnostic. It works alongside existing models, applications, workflow systems, logging tools, and cloud or on-prem environments. It does not replace them. Verify creates value by reducing reliance on reconstruction. Instead of searching logs, rebuilding prompts, re-querying context, or asking teams to piece together fragments, organizations can retrieve the decision record directly. For healthcare, Verify supports retained decision records for AI-assisted care and operational workflows. For banking and financial services, Verify supports decision evidence for transaction, risk, compliance, and customer workflows. For insurance, Verify supports retained records for claims, coverage, risk, and dispute workflows. The core shift is from reconstruction to retrieval. ## 19. Reference summary Obligra Verify is a model-agnostic system of record for AI-assisted decisions. It captures AI-assisted decisions as retained, reviewable, and verifiable decision records. Each decision record preserves the input, context, output, workflow metadata, validation results, integrity metadata, and retention information needed to retrieve and review the decision later. Verify is not logging, observability, monitoring, prompt tooling, model evaluation, or a generic AI dashboard. It is a decision record layer built for retention, retrieval, and verification. The product exists to close the post-inference record gap by replacing reconstruction from logs with direct retrieval of decision evidence. --- --- title: Network and HTTPS Egress slug: network-and-https-egress category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/network-and-https-egress canonicalUrl: "https://obligra.ai/resources/network-and-https-egress" llmTags: - llm-aligned - architecture-core - retrieval-tier-3 - supporting-reference --- # Network and HTTPS Egress _Architecture_ _Verify is reached over standard outbound HTTPS from trusted customer runtimes. The customer team owns the network path on both sides of the boundary — DNS resolution, TLS posture, egress proxies, NAT, firewall rules, and the customer-side observability that confirms the path is healthy — plus the inbound counterpart for customer-owned webhook receivers. The Verify platform does not require proprietary networking, private link, dedicated transport, or any customer-side network shape beyond the egress posture already in place for other modern SaaS APIs._ ## Overview Verify is reached over standard outbound HTTPS from trusted customer runtimes, and the network architecture customer teams need to support that is, by design, the same network architecture they already use for every other modern SaaS integration. In practice, this means most Verify integrations succeed at the network layer on the first attempt — backend services, Lambda functions, container tasks, and capture workers reach the public API using the customer’s existing egress posture. There is no customer-side requirement for private networking, dedicated interconnects, or proprietary transport. The tradeoff embedded in this design is intentional: the customer team owns the path from the runtime to the public boundary — DNS, TLS, proxies, NAT, firewall rules, and the observability that proves the path is healthy — in exchange for the freedom to adopt Verify without inventing new network conventions for it. > Verify is reached over standard public HTTPS. > > > > > The customer-side network is exactly the same path that any other outbound API integration uses. If the customer runtime can reach common SaaS APIs, it can reach Verify without bespoke network engineering. ## Why this matters Most Verify integrations succeed on the first attempt at the network layer. The minority that fail almost always trace back to customer-side network configuration that was either missed during onboarding or never validated against the active Production network path. Capture availability follows the egress path. When outbound HTTPS is blocked, slow, or intermittently routed through a misconfigured proxy, the symptoms surface as capture latency and retry behavior — which looks like an integration bug from the application layer and a healthy network from the network layer. The Sandbox-first validation loop only catches this if the network path used in Sandbox is faithful to the Production path. TLS posture and DNS behavior are equally customer-side. A runtime pinned to deprecated TLS versions, or a runtime that resolves through a corporate forwarder or split-horizon environment, carries that posture into every Verify call. Egress proxies, WAFs, and middle-box certificates compound the surface — header stripping, path rewriting, premature timeouts, and certificate-trust gaps all surface as confusing integration failures rather than clean network errors. The inbound counterpart matters when webhook receivers are in play. The customer team owns the path that accepts Verify-originated POSTs and routes them to the receiver, which means receiver outages are observable only through customer-side instrumentation. Without observability that distinguishes the network path from application health, an outbound capture outage and an upstream platform incident look identical. ## Recommended pattern The recommended customer-side network shape is the same as for any modern SaaS API integration: outbound HTTPS over the customer’s standard egress path, with modern TLS, and with customer-side observability that exposes path health independently from application health. ### Outbound (capture and retrieval) - Customer runtime resolves the Verify API hostname via the customer's standard DNS path. - Customer runtime opens an HTTPS connection over modern TLS (TLS 1.2 or higher). - Customer runtime presents the Verify API key as the standard X-Verify-Api-Key request header (or the bearer header for authenticated user/console workflows). - Customer runtime applies a bounded request timeout, fitting within the upstream request budget (for synchronous capture) or the worker's per-message budget (for queue-fed capture). - Customer runtime applies bounded retries with exponential backoff and jitter for transient failures. - Customer runtime emits customer-side observability — outcome class, retry attempt count, latency — partitioned by environment. ### Inbound (webhook receivers) - Customer webhook receiver is published behind the customer's standard public ingress (edge or load balancer), with HTTPS termination and the customer's existing WAF/edge protections. - Receiver accepts HTTPS POSTs from the Verify notification surface, ACKs fast, and enqueues for background processing. - Receiver tolerates retries from the notification surface — the same logical event may be redelivered if the original ACK is not observed. - Receiver emits customer-side observability — delivery rate, ACK latency, dead-letter rate — partitioned by environment. ## Customer-owned capture boundary in the outbound path In governed deployments, outbound HTTPS traffic to Verify commonly originates from the **Customer-Owned Proxy** rather than directly from the application runtime. The proxy becomes part of the trusted outbound path and evaluates governance controls before approved fields are transmitted. This shifts the network origin of outbound capture traffic from many application processes to a smaller set of customer-operated proxy instances. The egress posture is the same — standard HTTPS over modern TLS over the customer’s existing outbound plumbing — but the network plan and the customer-side observability for outbound capture should be oriented around the proxy fleet rather than every individual application runtime. ## Network boundary vs governance boundary Two related but distinct architectural concepts often surface in the same conversation: - **Network boundary** — defines *how* outbound traffic reaches Verify: DNS, HTTPS over modern TLS, proxies, NAT, firewalls, and the customer egress path. - **Governance boundary** — defines *where* capture decisions and field retention decisions are evaluated: typically inside the Customer-Owned Capture Boundary, before any approved fields cross the network boundary. The two are related — in governed deployments, the governance boundary sits in front of the network boundary, and outbound HTTPS originates from the trusted runtime that enforces governance. They remain distinct architectural concepts: a healthy network path does not by itself imply governance is enforced, and a complete governance posture does not by itself imply the network path is healthy. Both need to be validated independently. ## Architecture diagram The diagram below shows the customer-side network path for outbound capture and the inbound counterpart for webhook receivers. Every box is customer-owned; the Verify public API surface is the only external boundary. ![HTTPS path to Verify. Six horizontal stage cards trace the outbound network path: 01 Customer Runtime (trusted server-side workload initiates outbound HTTPS), 02 Customer-Owned Capture Boundary (teal-bordered hero card with GOVERNANCE header band; in governed deployments, outbound HTTPS originates here after governance runs), 03 DNS Resolver (customer DNS path resolves the Verify API hostname), 04 Proxy / NAT / Firewall (customer egress plumbing: forward proxy, NAT gateway, firewall, customer perimeter), 05 Public Internet (dashed-border card; standard internet path with no customer-side private networking required), and 06 Verify API (dark teal hero terminal card with VERIFY API header band; public HTTPS endpoint, receives only approved fields, no inbound access to customer environment). A NETWORK PROPERTIES band beneath the cards lists four callouts: HTTPS 443 (standard outbound port, no custom ports), TLS 1.2+ (modern TLS posture, no custom ciphers), Standard Egress (customer's existing outbound HTTPS plumbing), and No Private Networking (no interconnects, dedicated circuits, or private endpoints). Footer caption: the customer team owns the network path, Verify is reached over standard public HTTPS.](/diagrams/obligra-verify-https-path.svg) * The HTTPS path from a trusted customer runtime to the Verify public API. Governed deployments place the Customer-Owned Capture Boundary in the outbound path so governance runs before fields cross the network. * ![Outbound vs inbound Verify traffic, side by side. Left panel (teal header band labeled OUTBOUND · CAPTURE AND RETRIEVAL): Customer Runtime card (source) connected by an HTTPS · TLS 1.2+ arrow to a Verify API card (destination). Panel footer: capture and retrieval flow from the customer runtime to the Verify public API; the customer team owns the egress path. Right panel (dark teal header band labeled INBOUND · WEBHOOK DELIVERY): Verify Notification Surface card (source) connected by an HTTPS · TLS 1.2+ arrow to a Customer Webhook Receiver card (destination). Panel footer: webhook delivery from the Verify notification surface to a customer-published receiver; receivers ACK fast and enqueue. Footer caption: outbound and inbound are independent network paths; both use standard HTTPS over modern TLS.](/diagrams/obligra-verify-outbound-inbound-traffic.svg) * Outbound and inbound are independent network paths. Both use standard HTTPS over modern TLS and the customer team owns the corresponding ingress or egress plumbing. * ```text Outbound: customer runtime → Verify ───────────────────────────────────── Customer Runtime (trusted server-side) │ │ (1) DNS resolution ▼ Customer DNS / Resolver │ │ (2) HTTPS / TLS 1.2+ outbound (port 443) ▼ Customer Egress ├─ Forward proxy (if present) ├─ NAT gateway / customer router ├─ Customer firewall / egress allow-list └─ Customer perimeter │ │ (3) Public internet ▼ Verify Public API ── verify capture / retrieval / verification Inbound: Verify notification → customer webhook receiver ───────────────────────────────────────────────────────── Verify Notification Surface │ │ (a) HTTPS POST to customer-published URL ▼ Customer Edge / Load Balancer / WAF │ │ (b) Routing rules ▼ Customer Webhook Receiver │ │ (c) Fast ACK (2xx) │ (d) Enqueue for background processing ▼ Customer Queue + Worker │ ▼ Downstream Operational Surfaces ``` ## How it works The path is intentionally ordinary. Each layer is customer-owned and follows the customer’s existing conventions for outbound API integrations. ### DNS resolution The customer runtime resolves the Verify API hostname using the customer’s normal DNS path. In most production environments this is a configured resolver, a corporate forwarder, or the customer’s cloud-provider DNS. The Verify hostname is publicly resolvable — no private DNS zone or customer-side override is required. ### HTTPS and TLS Verify accepts HTTPS connections over modern TLS. Customer runtimes should use a modern TLS implementation provided by the runtime or HTTP client library and rely on standard certificate validation. If the customer’s egress proxy terminates and re-establishes TLS, the runtime must trust the proxy’s issuing CA for the customer’s middle-box certificate. ### Egress path The path from the runtime to the public internet is customer-controlled. Whether traffic passes through a forward proxy, a NAT gateway, a firewall with egress allow-listing, or a transit gateway depends on the customer’s environment. Verify imposes no requirement on this shape — only that the runtime can reach the public API hostname over HTTPS. ### Timeouts and retries The customer runtime applies a bounded request timeout matched to the upstream context (synchronous request, worker invocation, or scheduled job). Bounded retries with exponential backoff and jitter handle transient failures — but every retry path should preserve the same operational context so deduplication by retrieval-by-context remains available. ### Customer-side observability The customer runtime emits log lines and metrics for each capture or retrieval call — outcome class, retry count, latency, environment — without including the API key, the bearer token, or any authentication header value. ## Customer responsibilities The customer team owns the entire network path on both sides of the public boundary. Verify owns the API surface and the notification surface. The boundary between the two is the public HTTPS call. - Confirm DNS resolution from the trusted runtime to the Verify API hostname through the customer's standard resolver. - Confirm outbound HTTPS / TLS 1.2 or higher is permitted from the runtime through the customer's egress path. - Confirm customer proxies, firewalls, and WAFs do not strip the X-Verify-Api-Key or Authorization headers, do not rewrite paths, and do not impose timeouts shorter than the customer runtime's request budget. - Operate webhook receivers behind the customer's standard public ingress, with HTTPS termination, WAF rules, and load balancing the customer team already operates. - Apply bounded retries with exponential backoff and jitter. Avoid retry storms that compound network problems. - Tag customer-side network observability by environment so Sandbox issues do not page Production on-call. - Coordinate any platform, network, or security policy changes that affect the customer's egress path with the customer's platform team before Production rollout. - When troubleshooting, validate the network path independently from the application (curl from the runtime, DNS lookup, certificate chain inspection) before opening application-level investigations. ## Common mistakes The pitfalls below are the most common customer-side network issues observed during Verify rollouts. Most surface as intermittent capture failures rather than clean network errors — which is why they often look like application bugs on first inspection. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Pinning the runtime to deprecated TLS versions | Modern public APIs reject deprecated TLS handshakes. Capture fails at handshake time with messages that do not clearly indicate TLS as the cause. | Use TLS 1.2 or higher via the runtime's default TLS implementation. Inherit modern defaults rather than pinning. | | Egress proxy strips authentication headers | A misconfigured forward proxy that rewrites or strips X-Verify-Api-Key or Authorization headers causes capture to fail with auth errors that look like credential issues. | Validate that the customer egress proxy preserves all request headers end-to-end. Test from inside the runtime, not from a workstation. | | Proxy timeout shorter than runtime request budget | Egress proxies that terminate connections early surface as request timeouts the runtime cannot distinguish from upstream issues. | Align proxy timeouts with the runtime's request budget. Confirm there is no shorter-than-expected idle timeout in the path. | | DNS resolver returns stale or inconsistent results | Corporate forwarders or split-horizon DNS can produce inconsistent resolution that flakes between runtimes. | Validate DNS resolution from inside the runtime, not from a workstation. Use the same resolver chain in Sandbox and Production validation. | | Webhook receiver behind a WAF that rejects POSTs without warning | Customer WAF rules that block unsigned bodies, large payloads, or non-browser user agents can silently drop Verify notifications. | Configure the customer WAF to allow Verify-originated POSTs and confirm by emitting a synthetic event in Sandbox before Production rollout. | | Assuming the network path is healthy without independent validation | Capture works in development, breaks in Production, and the team spends days investigating application code while a NAT or perimeter change is the root cause. | Validate the customer-side network path independently from the application before promoting to Production — DNS, TLS, headers, proxy, latency. | | Inventing private link or IP allowlist requirements | Standard public HTTPS is sufficient for Verify integrations. Building a customer-side private networking shape adds complexity without value. | Use the customer's standard outbound HTTPS path. If the customer's security program requires egress allow-listing by hostname, apply it the same way as for other SaaS APIs. | ## Validation checklist Before promoting a Verify integration from Sandbox to Production, the following network-layer controls should all be in place. - DNS resolution from the trusted runtime to the Verify API hostname succeeds using the customer's standard resolver chain. - Outbound HTTPS over TLS 1.2 or higher succeeds from the trusted runtime, validated independently from the application. - Customer egress proxies (if any) preserve X-Verify-Api-Key, Authorization, and other request headers end-to-end. - Customer egress proxies and NAT have timeouts that allow the customer runtime's request budget to complete without premature connection termination. - Customer-side TLS certificate validation succeeds — including any middle-box certificate the customer's egress proxy presents. - Customer webhook receivers (if used) accept HTTPS POSTs from the Verify notification surface behind the customer's standard ingress and WAF rules. - Customer-side network observability captures outcome class, retry count, and latency per environment. - A Sandbox dry-run from the actual Production network topology (or a faithful staging mirror) has been performed. - The customer's platform and security teams have signed off on the egress path before Production rollout. ## Related documentation Pair this guide with the following resources for the full network and integration picture: - [Customer Integration Patterns — hub for the supported integration shapes that all use this network path.](/resources/customer-integration-patterns) - [Server-Side Capture Pattern — trusted server-side topology that originates outbound HTTPS to Verify.](/resources/server-side-capture-pattern) - [API Key Placement and Secret Storage — credentials carried over the network path described here.](/resources/api-key-placement-and-secret-storage) - [Webhook Delivery Architecture — inbound counterpart for customer-owned webhook receivers.](/resources/webhook-delivery-architecture) - [Environment Strategy — Sandbox vs Production network discipline across customer environments.](/resources/environment-strategy) - [Deployment Topology — where the Customer-Owned Capture Boundary sits in the deployment shape and how it relates to the network path.](/resources/deployment-topology) - [Reference Architecture: AWS — concrete deployment topology that illustrates the boundary placement and the outbound network path.](/resources/reference-architecture-aws) - [Customer Security Overview — broader customer-side security posture around Verify integrations.](/resources/security-overview) --- --- title: Queue-Based Capture Pattern slug: queue-based-capture-pattern category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/queue-based-capture-pattern canonicalUrl: "https://obligra.ai/resources/queue-based-capture-pattern" llmTags: - llm-aligned - architecture-core - integration - retrieval-tier-3 - supporting-reference --- # Queue-Based Capture Pattern _Architecture_ _As Verify integrations scale into higher-volume production workloads, customer teams routinely discover that synchronous in-request capture is no longer the right shape. Queue-based capture is the asynchronous counterpart: the producer assembles a self-contained message carrying every field capture needs — including operational context — and enqueues it on customer-owned queue infrastructure. An idempotent worker reads the queue, submits to Verify with a stable retry key, and uses retrieval-by-context to safely deduplicate when capture status is uncertain. The tradeoff is explicit: immediate visibility is traded for resilience, decoupling, and a much friendlier retry posture under transient downstream slowness._ ## Overview Some customer workflows are better served by asynchronous, queue-fed capture than by synchronous in-request capture. In practice, the architectural signal is clear: when the AI-assisted workflow produces output ahead of when capture should occur, when capture should not block the customer-facing request path, or when bursty input rates would overwhelm a synchronous capture path, the queue-based pattern is the right shape. Many teams discover this during their first scale test — the synchronous pattern that worked beautifully in Sandbox falls behind under burst load, and the queue is what restores the headroom. The pattern is entirely customer-side. The customer team owns the queue, the message shape, the consumer worker, the retry posture, the dead-letter routing, and the observability. Verify’s public API is the boundary the worker calls over HTTPS — everything upstream of that boundary stays inside the customer’s existing operational fabric, which is part of what makes the pattern easy to adopt. > The queue is customer-owned. The worker is customer-owned. Verify is the boundary. > > > > > SQS, Kafka, RabbitMQ, customer database queues, and equivalent infrastructure all work. Verify does not provide a managed queue and does not require a specific queueing technology. ## Why this matters Async capture trades immediate visibility for resilience and decoupling. The tradeoff is the right one for a wide class of workflows — but only if operational context survives the queue boundary and the consumer worker stays idempotent. Teams that get one half of that right and the other half wrong consistently report the same downstream symptom: duplicate records that look like a Verify bug and are, on inspection, a consumer-shape issue. Decoupling is what protects the request path. Synchronous capture inside the customer-facing request couples capture latency to user-facing latency, and queue-fed capture removes that coupling. In practice, bursty workloads benefit from the buffer: AI-assisted workflows that produce output in bursts (batch jobs, scheduled processing, event-driven triggers) gain queue-backed smoothing for free, without any additional code on the producer side. Workers can take longer retry budgets than synchronous handlers because they are not coupled to user-facing timeouts. That latitude is what turns transient downstream slowness into a recoverable condition rather than a dropped event — and it is the single largest operational benefit of moving to the queue-based pattern in the first place. The pattern has two requirements that, when missed, cause subtle problems. Operational context must survive the queue boundary — the worker is decoupled from the producer and cannot reconstruct workflowId or operationalContext if the message did not carry them. And consumers must be idempotent, because queues redeliver under restart, dead-letter, or visibility-timeout expiration, and a non-idempotent worker creates duplicate records from a single business event. Neither requirement is exotic; both have to be designed in deliberately. Retrieval-by-context resolves uncertainty cleanly. When capture status is uncertain after a timeout, retrieval-by-context is the safest way to determine whether the record already exists before retrying. ## Recommended pattern The recommended customer-side queue-based capture pattern serializes a self-contained capture-intent message, drives it through a durable customer queue, and lets an idempotent worker submit to Verify with a stable retry key. ### Message shape (self-contained) - workflowId — the stable operational workflow identifier the customer team uses (claims-review, fraud-triage, intake-summary, etc.). - operationalContext — the customer-side retrieval keys (claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId). - AI-assisted context — the output to be preserved, plus any non-sensitive model metadata (model.provider, model.modelId). - environment — Sandbox or Production, so the consumer can confirm scope at dispatch time. - retryKey — a stable, deterministic key the producer generates from the business event; the consumer uses it across attempts so duplicate-capture is detectable. - producedAt — when the message was enqueued (for customer-side observability and queue-age alerting, not for Verify). ### Consumer behavior - Dequeue with at-least-once semantics; the consumer must tolerate redelivery without producing duplicate records. - Confirm the active environment matches the consumer's expected scope. Refuse to dispatch on environment mismatch. - Submit to the Verify Capture API over HTTPS using the environment-scoped credential and the message's retryKey. - On successful capture, acknowledge the queue message — the message is now durably represented as a retained decision record. - On retryable failure, return the message to the queue with backoff. The next attempt uses the same retryKey. - On non-retryable failure, route to a dead-letter queue with customer-side alerting and a documented remediation runbook. - On uncertain capture status (timeout, connection drop after submit), retrieve by operationalContext and decisionRecordId. If the record was already created, acknowledge without resubmitting. ## Architecture diagram The diagram below is a customer-safe view of queue-based capture. The queue and the worker are customer-owned; Verify’s public API is the only external boundary. ```text Customer-owned Verify (public boundary) ───────────────────────── ───────────────────────── Producer (AI-assisted workflow output) │ │ Assemble self-contained message: │ workflowId │ operationalContext │ AI-assisted context │ environment │ retryKey │ producedAt │ ▼ Customer Durable Queue (SQS / Kafka / RabbitMQ / customer DB queue / equivalent) │ │ at-least-once delivery ▼ Customer Capture Worker (idempotent) │ │ (1) Confirm active environment │ (2) Submit to Verify Capture API │ (HTTPS, X-Verify-Api-Key, retryKey) │ ├──────────────────────────────────────────▶ Verify Capture API │ │ │ ◀──── decisionRecordId, retrieval keys ─────┤ │ ▼ │ Retained Decision Record │ │ (3a) On success: ACK queue message │ (3b) On retryable failure: return to queue (backoff) │ (3c) On non-retryable failure: DLQ + customer alerting │ (3d) On uncertain status: │ Verify Retrieval API ─── retrieve by operationalContext │ to confirm record exists │ ▼ Customer Observability ├─ Outcome class, retry count, queue age, env, workflowId └─ decisionRecordId (when returned) ``` ## How it works The pattern is a separation of concerns: the producer assembles a self-contained message, the queue carries it durably across the customer-side boundary, and the idempotent consumer submits to Verify. ### Producer side The producer is wherever the AI-assisted workflow output is first available. The producer is responsible for assembling a message that carries everything the consumer needs — the consumer should never need to look back at the producer’s state to enrich the message. ### Queue side The queue is a customer-owned durable buffer. It guarantees at-least-once delivery; the customer team configures visibility timeouts, redelivery policies, and dead-letter routing using whatever queue technology they already operate. ### Consumer side The consumer dispatches the message to the Verify Capture API. The retryKey carried in the message is the key to idempotency — Verify uses it to detect duplicate submissions, and the consumer uses retrieval-by-context to confirm capture status when the outcome is uncertain. ### Uncertainty handling A timeout after submission is not a definitive failure — the record may have been created on the platform side before the connection dropped. The safe consumer response is to call retrieval-by-context using the message’s operational identifiers. If the record exists, acknowledge the queue message without resubmitting. If it does not, retry with the same retryKey. ## Customer responsibilities The customer team owns the queue, the message shape, the consumer worker, the retry posture, the dead-letter handling, and the customer-side observability. Verify owns the public API. The boundary between the two is the HTTPS call from the worker. Queue ownership covers the durable buffer itself (whether SQS, customer Kafka, customer RabbitMQ, customer database queues, or equivalent), the visibility timeouts, the redelivery policy, and the dead-letter routing. The consumer is the worker that turns queue messages into Verify capture calls — idempotent by design, environment-aware before dispatch, and bounded in its retry budget. The message shape is treated as a contract. The producer assembles a self-contained message that carries workflowId, operationalContext, AI-assisted context, environment, retryKey, and producedAt; the retryKey is generated deterministically from the business event so retries across consumer restarts produce the same key. When capture status is uncertain after a timeout, the worker resolves it with retrieval-by-context rather than blind resubmission. Customer-side observability captures queue age, dequeue rate, capture outcome class, retry attempt count, and dead-letter rate, partitioned per environment. The message shape, the retry-key derivation, and the consumer behavior are documented in the customer-side runbook so the next engineer can extend or operate the integration without reverse-engineering it. ## Common mistakes The mistakes below are the patterns that surface most often in queue-based capture integrations. The asynchronous nature of the pattern means most of these appear only under retry, restart, or redelivery — not during happy-path testing — which is why a Sandbox dry run that exercises failure paths is the lowest-cost way to find them. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Thin queue messages that omit operational context | The consumer cannot reconstruct retrieval keys from the message alone; reviewers later cannot retrieve the record using business identifiers they already know. | Make the message self-contained. workflowId, operationalContext, AI-assisted context, environment, and retryKey all live inside the message. | | Generating retryKey inside the consumer | Consumer-generated retry keys are different across redeliveries; capture is submitted with different keys and duplicate records appear. | Generate retryKey at the producer, deterministically from the business event. The same business event always produces the same retryKey. | | Blindly resubmitting after a timeout | A timeout means capture status is uncertain — the record may already exist. Blind resubmission creates duplicate retained decision records. | Retrieve by operationalContext to confirm capture status. If the record exists, acknowledge without resubmitting. | | Acknowledging the queue message before capture succeeds | If capture fails after the ACK, the message is lost. Verify never receives the retained decision record for that business event. | Acknowledge only after capture succeeds. On retryable failure, return the message to the queue. | | Sharing one queue across Sandbox and Production | Sandbox messages get dispatched to Production capture (or vice versa); records land in the wrong environment with no clean failure mode. | Distinct queues per environment. The consumer confirms the message's environment matches its own scope before dispatch. | | No dead-letter routing or alerting | Persistent failures fill the queue, block live deliveries, and create silent operational gaps. | Route non-retryable failures to a dead-letter queue with customer-side alerting. Document the remediation runbook. | | Unbounded retry loops inside the consumer | A persistent failure keeps the consumer busy retrying one message forever; queue throughput collapses; queue age grows. | Bound consumer retries with exponential backoff and jitter. Route to DLQ after a documented attempt count. | | Treating queue age as a Verify availability issue | Queue age depends on the consumer's processing rate and the customer-side queue policy — Verify availability is one input among many. | Measure and report consumer dispatch latency, capture call latency, and queue age separately. The triage path is different for each. | ## Validation checklist Promotion is a moment where it is easy to miss a control because the consumer “just works” on the happy path. The checklist below is a final pass that confirms the customer-side queue-based capture posture is in place before Production traffic begins flowing through the worker. Before promoting a queue-based integration: - Distinct durable queues per environment — Sandbox and Production messages never share a queue. - Queue messages are self-contained — workflowId, operationalContext, AI-assisted context, environment, retryKey, and producedAt all present. - retryKey is generated deterministically at the producer from the business event; the same business event always produces the same key. - Consumer is idempotent — at-least-once delivery produces exactly one retained decision record per business event. - Consumer confirms the message's environment matches its own scope before dispatch. - Consumer applies bounded retries with exponential backoff and jitter; the retryKey persists across attempts. - Consumer uses retrieval-by-operationalContext to confirm capture status when uncertain after a timeout. - Dead-letter routing is in place for non-retryable failures with customer-side alerting and a documented remediation runbook. - Customer-side observability captures queue age, dispatch latency, capture latency, outcome class, retry count, and dead-letter rate, partitioned per environment. - A Sandbox dry-run has exercised consumer restart, duplicate redelivery, and timeout-uncertainty resolution paths end-to-end. ## Related documentation The pages below cover the architectural decisions queue-based capture depends on most directly: where the consumer worker sits, how operational context travels with each message, and how the credential and environment scope hold across the queue boundary. - [Server-Side Capture Pattern — trusted server-side topology the consumer worker sits inside.](/resources/server-side-capture-pattern) - [Operational Context Mapping — retrieval keys carried in every queue message.](/resources/operational-context-mapping) - [API Key Placement and Secret Storage — credential discipline for the consumer worker.](/resources/api-key-placement-and-secret-storage) - [Environment Strategy — Sandbox vs Production discipline for queues and consumers.](/resources/environment-strategy) - [Customer Integration Patterns — architecture hub covering queue-based capture alongside other patterns.](/resources/customer-integration-patterns) - [AWS Lambda Integration Pattern — Lambda is a common runtime for queue-fed consumer workers.](/resources/aws-lambda-integration-pattern) - [Container / ECS Integration Pattern — container services are a common runtime for long-running consumer workers.](/resources/container-ecs-integration-pattern) - [Webhook Delivery Architecture — customer-side downstream surfaces that pair with queue-based capture.](/resources/webhook-delivery-architecture) - [Verify SDK Reference — retry and idempotency behavior for capture-side calls.](/resources/verify-sdk-reference) --- --- title: Security overview slug: security-overview category: Trust & Security retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/security-overview canonicalUrl: "https://obligra.ai/resources/security-overview" llmTags: - llm-aligned - trust-security - retrieval-tier-3 - supporting-reference --- # Security overview _Trust & Security_ _Verify is a system of record for AI-assisted decisions, not a security platform. The customer continues to own application security, identity and access, user permissions, model governance, cloud and network controls, and the workflow design that produces AI-assisted output. Verify operates the managed decision record layer that retains the evidence reviewers need months later. The two responsibilities compose into a coherent security model for AI-assisted operational programs: customer governance enforces the boundary; Verify retains the record once governance approves what crosses it._ ## Overview The security conversation around AI-assisted operational workflows tends to begin in the same place: organizations discover that the security model they have refined over years for deterministic software does not cleanly apply to probabilistic workflows. Outputs are not stable across model versions. The same inputs may produce different outputs months apart. Reviewers asked to look back at a single AI-assisted decision months later cannot reliably reconstruct it by re-running the workflow — by then the model, the prompts, the data, and the surrounding workflow have all moved on. That gap is the security problem Verify is built around. In practice, Verify preserves retained decision records for AI-assisted decisions at the moment they happen, so reviewers can retrieve the record later using the same business identifiers the customer team already uses operationally. Application security, user access, model governance, and workflow design remain customer-owned; Verify provides the layer underneath that keeps the record available for review long after the workflow has changed. The tradeoff is intentional: customer teams keep every control they already operate, and gain a record layer they would otherwise have to build. ## Why this matters for GenAI workflows GenAI changes three things at once for an enterprise security program: it changes what evidence exists, what review looks like, and what trust requires. Each of these has direct implications for how security teams think about AI-assisted operational workflows, and the implications compound — a program that addresses one but not the other two ends up with gaps that are difficult to defend later. ### Evidence changes In a traditional workflow, the application logs and the authoritative system of record are usually sufficient evidence — the workflow is deterministic, and re-running it against the same data produces the same result. In an AI-assisted workflow, the outputs depend on a model version, a prompt context, retrieved data, and other inputs that evolve continuously. Logs may show that a decision was made, but not what the workflow saw at the moment it made the decision. Retained decision records close that gap. ### Review changes Reviewers arriving later — compliance, audit, fraud, legal, operations — need to look at one specific decision, not the workflow in aggregate. They retrieve by the business identifier they already know (claimId, encounterId, transactionId, escalationId, reviewCaseId) and inspect the retained record. In practice, retrieval-oriented review replaces the workflow of pulling logs, screenshots, provider history, and support tickets together to reconstruct what happened. ### Trust changes Trust in an AI-assisted decision cannot rest on the model alone. It rests on the customer team’s ability to retrieve and inspect the decision record — to confirm that the retained record is the record under review, that the captured context matches expectations, and that the review process operates over an authoritative artifact. Runtime controls remain necessary; what GenAI adds is a need for retained, retrievable, review-ready records. ## Verify's role Verify is a retained decision record layer for AI-assisted decisions. Its role is narrow, deliberate, and customer-safe. - Receive selected decision context submitted by trusted customer runtimes through a public HTTPS capture API. - Preserve that context as a retained decision record indexed by customer-attached operational context (workflowId, claimId, encounterId, transactionId, escalationId, reviewCaseId, policyId, and similar stable business identifiers). - Support retrieval of the retained record using the same operational context the customer team already uses day-to-day. - Expose customer-visible verification status that supports review-oriented confidence in the retained record without disclosing internal platform mechanics. - Surface review workflows through the Verify Console for customers whose teams need to inspect, search, and act on retained records. Verify is not an AI governance dashboard, an observability or telemetry platform, a trust-and-safety monitoring tool, or a substitute for the customer’s own controls. The role is preservation and retrieval — making AI-assisted decisions reviewable later under the customer’s own operational program. ## Customer responsibility Everything outside the retained decision record layer remains in the customer’s control. This is intentional. AI workflow design, user access, credentials, model selection, cloud controls, and the policies that govern review are decisions only the customer team can make for its organization. ### What customers continue to own Customer responsibility spans the AI-assisted workflow itself, the runtime the workflow lives in, the people who access it, the credentials that authenticate to Verify, the operational context that becomes the retrieval key, and the review process that determines outcomes. Each is a customer-side decision shaped by the customer’s organization, regulatory environment, and risk posture. ### Why the boundary is here The boundary between customer responsibility and Verify’s role is the public HTTPS call from the customer runtime to the Verify Capture API. Everything before the call — including which workflows produce which records, who can submit them, what context is included, and what business identifiers are attached — belongs to the customer team. Everything after the call — preserving the record, supporting retrieval, exposing verification status — belongs to Verify. ## Shared responsibility The Shared Responsibility Model below summarizes how customer responsibility and Verify’s role compose into a coherent security model for AI-assisted operational workflows. | Area | Customer responsibility | Verify role | | --- | --- | --- | | AI workflow design | Customer defines workflow behavior, prompt strategy, model selection, and review process. | Preserves submitted retained decision records and supports later retrieval and review. | | User access and roles | Customer manages identity, authentication, and authorization decisions across their systems. | Supports record access through customer-configured workflows and Console permissions. | | API key protection | Customer stores API keys server-side in a secret manager, scoped per environment. | Provides environment-aware API key issuance and the public authenticated API surface. | | Capture integration | Customer places capture inside a trusted server-side runtime (backend, Lambda, container, queue worker). | Receives retained decision records over the public HTTPS API. | | Operational context | Customer chooses stable business identifiers (claimId, encounterId, transactionId, etc.) to attach at capture. | Supports later retrieval keyed on the operational context attached at capture time. | | Record retrieval | Customer searches by known workflow and business context aligned with their authoritative systems. | Returns retained decision records where authorized by the customer's configured access. | | Review and verification | Customer determines the review process — who reviews, when, what outcome is required. | Provides customer-visible verification-oriented record status for review workflows. | | Customer environment security | Customer secures their own systems, networks, runtimes, and operational tooling. | Provides the customer-facing integration surface and the retained record layer. | ## Shared Responsibility Model The visual below summarizes the same model as a three-column operational view — customer-owned responsibilities on the left, the shared operational boundary in the middle, and Verify’s responsibilities on the right. ```text Customer responsibilities Shared operational Verify responsibilities boundary ───────────────────────── ────────────────── ─────────────────────── AI workflow design Preserve retained (prompts, models, behavior) decision records │ (per submission) User access and roles │ (identity, auth, RBAC) │ Support retrieval │ by operational context API-key protection │ (workflowId, claimId, (server-side secret stores) │ encounterId, ───────┼────── transactionId, Operational context │ escalationId, (stable business identifiers) │ reviewCaseId, ...) │ Capture integration │ Expose verification- (server-side, trusted runtime) │ oriented record status │ (customer-visible) Review workflows │ (who reviews, when, outcomes) Surface review workflows in the Verify Console (per customer access) The public HTTPS call is the boundary. Everything before the call belongs to the customer team. Everything after the call belongs to Verify. ``` ## Security considerations The considerations below summarize the most important customer-side security decisions for an enterprise AI-assisted workflow that uses Verify. They are not new — each is the customer team’s existing security practice applied to the AI-assisted workflow that produces the records. ### Credential discipline Verify API keys are environment-scoped (Sandbox or Production) and belong only inside trusted server-side runtimes. They are read from the customer’s secret manager at process start, cached in memory, and never written to disk or to log lines. Rotation cadence is a customer decision. ### Network posture Verify is reached over standard public HTTPS using modern TLS. The customer team controls DNS resolution, the egress path, proxies, NAT, firewalls, and webhook ingress. No customer-side private networking or proprietary transport is required. ### Operational context discipline The operational context attached at capture time is the retrieval contract reviewers will rely on later. Stable, customer-recognizable identifiers (issued by the customer’s authoritative system) make retrieval durable across releases. Operational context should name the work — not embed PHI, PII, prompt text, or model output bodies. ### Environment separation Sandbox and Production stay separated end-to-end — credentials, secret-manager paths, runtime configuration, downstream review queues, observability, and CI/CD. Records do not move between environments; Sandbox records are not Production evidence. ## Implementation considerations The integration shape determines where credentials live, how operational context is propagated, and how retry and observability work. The Architecture section covers each shape in detail; the points below summarize the security-relevant implications. - Capture lives in trusted server-side runtimes — backend services, Lambda functions, container tasks, or queue workers. Frontend and mobile applications call the customer backend, which submits to Verify on their behalf. - Credentials are read once at runtime start (or Lambda cold start) from a customer-controlled secret manager, cached in process memory, and never written to disk. - Operational context is attached at capture time using business identifiers issued by the customer's authoritative system of record. - Sandbox-first validation is mandatory before any Production rollout — the customer team validates capture, retrieval, and verification end-to-end in Sandbox using representative operational context. - Observability is partitioned by environment so Sandbox noise never reaches Production alerting, and Production signal never gets buried in Sandbox traffic. - Customer review workflows treat retained records as the authoritative artifact for inspection; webhook payloads are notifications, not records. ## Common misconceptions The misconceptions below are common during enterprise security review of Verify integrations. Each clarifies a boundary that the Shared Responsibility Model already implies but is worth surfacing explicitly. | Misconception | How to think about it | | --- | --- | | Verify is an AI governance dashboard. | Verify is a retained decision record layer. It preserves what was decided and supports retrieval — it does not score, gate, or govern AI behavior. Governance remains a customer-owned program. | | Verify monitors runtime AI behavior in real time. | Verify receives submissions from customer runtimes and preserves them as retained decision records. Runtime monitoring of customer systems is a customer responsibility. | | Adopting Verify makes the organization compliant. | Verify supports compliance review by preserving review-ready records. Compliance posture remains shaped by the customer's policies, controls, regulatory environment, and audit program. | | Verify holds copies of customer source systems. | Verify receives only what the customer chooses to submit at capture time. Source systems remain customer-owned and are the authoritative system of record. | | Verify can be reached from frontend or mobile applications. | Verify is a server-side API. Frontend and mobile applications call the customer backend, which submits to Verify on their behalf using server-side credentials. | | Webhook payloads are the retained record. | Webhook payloads are notifications. The retained decision record is the authoritative artifact and is retrieved through the Verify API using decisionRecordId or operationalContext. | | Sandbox records and Production records are interchangeable. | Sandbox is for validation. Production is the operational record. Records do not move between environments — Sandbox is not Production evidence. | ## Related documentation Pair this overview with the following pages for the full security and integration picture: - [Data handling and residency — what customers submit, what Verify preserves, and the customer-side data decisions involved.](/resources/data-handling) - [Record integrity and verification — customer-visible verification model for retained decision records.](/resources/record-integrity-and-verification) - [Compliance approach — how Verify fits into broader compliance and governance programs.](/resources/compliance-approach) - [API Key Placement and Secret Storage — customer-side credential discipline for the public API.](/resources/api-key-placement-and-secret-storage) - [Environment Strategy — Sandbox vs Production separation discipline.](/resources/environment-strategy) - [Operational Context Mapping — choosing stable business identifiers for retrieval.](/resources/operational-context-mapping) - [Server-Side Capture Pattern — the trusted server-side topology Verify integrations sit inside.](/resources/server-side-capture-pattern) --- --- title: Server-Side Capture Pattern slug: server-side-capture-pattern category: Architecture retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/server-side-capture-pattern canonicalUrl: "https://obligra.ai/resources/server-side-capture-pattern" llmTags: - llm-aligned - architecture-core - integration - retrieval-tier-3 - supporting-reference --- # Server-Side Capture Pattern _Architecture_ _Most Verify integrations evolve along a predictable curve: builder teams start with the simplest server-side capture shape, and operations teams need a governance boundary in front of it before Production rollout. Both shapes are server-side, and both call the same Verify API. Direct integration submits records straight from the customer backend and fits builder, evaluation, and Sandbox workflows where capture decisions can reasonably live in application code. Governed integration submits through a customer-owned proxy that evaluates a Capture Decision Policy and a Field Retention Policy before any record reaches Verify, and fits Production, enterprise, and regulated workloads where capture decisions and field retention need to be enforced inside the customer environment and reviewed independently from application logic._ ## Overview Organizations integrating Verify into a production AI-assisted workflow consistently end up at the same architectural conclusion: capture should run from a trusted server-side runtime, not from anywhere else. The reason is not preference — it is the structural reality that the credentials, the operational context, the workflow output, and the trust boundary all naturally co-locate on the backend that produced the AI-assisted decision. Server-side capture is the recommended pattern because it is where the right inputs already live. In practice, this means customer systems call Verify from trusted backend or workflow services after an AI-assisted workflow produces an output. The customer backend holds the API key, attaches the operational context reviewers will later retrieve by (claimId, encounterId, transactionId, escalationId, policyId, workflowId), and submits the retained decision record. The pattern preserves the customer's trust boundary while keeping the AI-assisted decision context co-located with the workflow that produced it — which is precisely what makes review months later possible. > Verify capture is for trusted server-side environments only. > > > > > Frontend applications, mobile clients, embedded devices, and other untrusted runtimes should never call Verify directly. They should call the customer backend, which submits to Verify on their behalf. ## Direct vs governed server-side capture Both supported server-side capture patterns are architecturally server-side. The tradeoff between them is not where capture runs — it is where capture decisions and field retention are enforced. In direct integration, the decisions are made implicitly inside the customer backend. In governed integration, the decisions are made explicitly inside a customer-owned proxy that runs governance before any record reaches Verify. Both are valid; the right choice depends on the audit and review obligations the workflow will carry once it is in Production. ![Direct versus governed server-side capture, side by side. Left panel direct integration: customer backend submits records directly to the Verify API over HTTPS, suited to builder, evaluation, and sandbox workflows. Right panel governed integration: customer backend submits to a customer-owned proxy that evaluates a capture decision policy and a field retention policy before forwarding only approved fields to the Verify API over HTTPS, suited to production, enterprise, and regulated workloads.](/diagrams/obligra-verify-direct-vs-governed-server-capture.svg) * The Verify API is the same endpoint in both patterns. The difference is whether governance runs inside the customer environment first. * ### Direct server-side capture In direct integration, the customer backend submits retained decision records directly to the Verify API. There is no intermediate governance layer; the capture surface is the simplest shape that still preserves the trust boundary, and the operational cost of standing it up is correspondingly low. Many teams find this is the right shape for builder workflows, evaluation, internal testing, and Sandbox validation — contexts where capture decisions and field-retention rules can reasonably live in application code, and where the integration optimizes for speed of feedback over governance enforcement. The tradeoff is that capture decisions are then coupled to the deployment cadence of the application code that makes them, which becomes a constraint once the workflow moves into Production review. ### Governed server-side capture In governed integration, the customer backend submits to a Customer-Owned Proxy that evaluates two independent governance layers locally: a Capture Decision Policy that decides whether a workflow output becomes a retained record, and a Field Retention Policy that decides which fields are permitted to leave the customer environment. Both evaluations occur inside the customer trust boundary before any data is transmitted to Verify. This is the recommended shape for production, governance, enterprise, and regulated workloads. Capture and field-retention rules live in a versioned policy file owned by the customer team, not in application code; the integration optimizes for review and audit discipline over speed of feedback. The tradeoff is intentional — customer teams accept the additional infrastructure surface in exchange for capture decisions that are reviewed, versioned, and enforceable on their side of the boundary. > The Customer-Owned Proxy sits inside the customer trust boundary and is a customer-side component, not a Verify-managed deployment shape. The Verify API is the same endpoint either way. ## Customer-owned capture boundary The Customer-Owned Proxy is a small, customer-operated service that sits in front of the Verify API and acts as the governance boundary for capture. In practice, customer teams deploy it with whatever infrastructure standard their organization already follows — CloudFormation, Terraform, or customer-managed infrastructure. The architecture is the same in every case; the choice follows existing customer infrastructure standards rather than introducing a new one. The proxy’s job is to evaluate capture decisions and field retention before anything crosses to Verify. It decides whether the interaction becomes a retained decision record at all (capture or skip), and for captured interactions it decides which fields are permitted to leave the customer environment (allow, drop, redact, truncate, or neverForward). Sensitive fields can be redacted in place, large fields can be truncated, and unauthorized fields can be blocked entirely — all inside the customer trust boundary, and all before any field crosses the customer’s network edge. What reaches the Verify API is the result of those decisions: only approved fields, on the records the customer team chose to retain. This is what makes the proxy a governance component rather than an infrastructure component. > Verify is not a surveillance logger. Customers determine what becomes a retained decision record. Verify receives only approved fields forwarded by the Customer-Owned Proxy. ## How capture policies fit The Customer-Owned Proxy evaluates two policy decisions independently, and understanding the ordering is the difference between a policy that does what the customer team expects and one that surprises them in audit. The first decision asks whether this interaction should be captured at all. The second asks, for interactions that are captured, which fields may be transmitted to Verify. The Capture Decision Policy runs first, resolving to one of two outcomes — `capture` or `skip`. The Field Retention Policy runs only on the interactions the first policy elects to capture, and resolves each field to one of five outcomes: `allow`, `drop`, `redact`, `truncate`, or `neverForward`. Both evaluations occur inside the Customer-Owned Proxy before any data is transmitted to Verify, and the ordering is important: skipping the first policy means the second policy never runs. For the policy contract, file shape, evaluation order, and field retention outcomes, see [Configuring an AI Capture Policy](/resources/configuring-an-ai-capture-policy) . ## Governed server-side capture diagram The end-to-end flow for governed server-side capture runs from the customer application all the way through verification. The shape below is the canonical Production deployment shape most enterprise customers converge on. ```text Customer Application │ ▼ Customer Backend │ ▼ Customer-Owned Proxy │ ▼ Capture Decision Policy │ ▼ Field Retention Policy │ ▼ Verify API │ ▼ Decision Record │ ▼ Verify Console │ ▼ Verification ``` In direct server-side capture, the customer-owned proxy and the two policy layers are not present — the customer backend calls the Verify API directly. The downstream surfaces (decision record, Verify Console, verification) are the same in both patterns. ## When to use direct vs governed capture The decision between direct and governed capture is rarely binary in practice — most customers begin with direct capture in Sandbox and move to governed capture before Production rollout. The matrix below summarizes the recommended pattern for the scenarios customer teams encounter most often during architectural planning. | Scenario | Recommended pattern | | --- | --- | | Builder onboarding | Direct | | First Sandbox record | Direct | | Internal tooling | Direct | | Production workload | Governed | | Governance program | Governed | | Enterprise deployment | Governed | | Regulated workload | Governed | In practice, organizations adopt the governed pattern at the same moment they adopt other Production-grade governance components — usually as part of the cutover from Sandbox validation to first Production traffic, not after Production rollout has already happened. ## AWS deployment options AWS customers commonly deploy the Customer-Owned Proxy using one of two managed deployment artifacts: **CloudFormation** for AWS-native stack management, or **Terraform** for infrastructure-as-code standardized across providers. Both methods deploy the same components — the API Gateway, the Lambda proxy, the capture policy, and the customer-owned capture boundary that holds them together — and both implement the same architecture. The choice follows existing customer infrastructure standards. For deployment topology and pattern selection, see: - [Customer Integration Patterns — runtime and governance pattern selection guidance.](/resources/customer-integration-patterns) - [Reference Architecture: AWS — customer-side deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) ## Why server-side capture matters The trust boundary for Verify lives inside the customer backend, not the customer’s frontend, and that framing follows from a few concrete properties of the integration rather than from style preference. Three of those properties are worth being explicit about, because each one is load-bearing on its own. First, the Verify API key is an operational credential. It authorizes record creation against a specific environment, and the operational discipline that surrounds it — read it from a secret manager, scope it by role and network, rotate it when exposure is suspected — is the same discipline customer teams already apply to database passwords. None of those controls translate cleanly to a frontend runtime, and any deployment that puts an API key in browser-reachable code creates a credential-exposure surface that is difficult to walk back later. Second, stable operational context already exists in the customer backend. The backend already knows the claim, encounter, transaction, escalation, policy, or workflow reference for the work it is performing — attaching that context at capture time is a straightforward extension of code that already runs. The tradeoff for capturing elsewhere is sharp: a frontend or untrusted runtime would need to reconstruct that context, and the reconstruction rarely matches the customer-side authoritative system on the first attempt. Third, the customer backend is the only runtime where retry behavior can be operated safely. Bounded retries, exponential backoff, retry-key idempotency, and customer-side observability all need a trusted runtime to run inside; none of them are safe to operate from a browser tab or a mobile device. Submitting AI-assisted decision context from an untrusted runtime would expose credentials, lose operational context, and undermine the retrieval surface reviewers depend on later — which is why the customer backend is the right place for capture, and everything upstream of it stays inside the customer-side trust model the customer team already operates. ## Recommended pattern The canonical topology for Verify capture is a short chain from the source of work, through the customer application and customer backend, into the AI-assisted workflow, and finally into Verify. ```text User or Internal Workflow → Customer Application → Customer Backend or Workflow Service → AI Workflow Produces Output → Verify Capture API ``` The chain reads in the order of operational responsibility. Work is initiated by a user or internal workflow — a claimant submits a claim, an agent opens a case, a scheduled job picks up a batch, or an internal workflow advances a stage. The customer application surfaces that initiation to the customer backend, which can be a web app, a mobile app, an internal console, or another service in the customer’s distributed system. The customer backend or workflow service is where capture lives. It is the trusted runtime that holds the Verify API key, attaches operational context, and submits the retained decision record. The AI-assisted step runs inside that backend, producing the output the customer team wants preserved — and capture happens after that step, so the output, the workflow context, and the operational identifiers are all preserved together. The Verify Capture API is the customer-facing API that records the retained decision record for later retrieval, inspection, and verification. ## Capture sequence A typical server-side capture call follows a short, ordered sequence inside the customer backend. - Customer workflow receives a request or work item — for example, a new claim, an inbound transaction, an open case, or a queued message. - AI-assisted workflow produces an output — a summary, classification, recommendation, routing decision, or escalation signal. - Backend prepares the capture payload — assembling the workflow context, the AI-assisted output, and the supporting fields the retained record will carry. - Backend attaches workflowId — a stable identifier for the operational workflow that produced the record. - Backend attaches operationalContext — the business identifiers reviewers will use later to retrieve the record (claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId). - Backend includes model and provider metadata where available — model.provider and model.modelId, plus any non-sensitive aiAssistedContext. - Backend submits the retained decision record to Verify over HTTPS, authenticated with the environment-scoped API key. - Verify returns record information — typically including a decisionRecordId, retrieval keys derived from operationalContext, the environment value, and the initial verification state. - Customer system stores the decisionRecordId if needed — useful for direct inspection and verification calls later. Most retrieval workflows do not depend on it. - Operators later retrieve by operational context — reviewers retrieve the retained record using the business identifiers their teams already use day-to-day. ## API key placement The Verify API key is the credential that authorizes the customer backend to submit retained decision records against a specific environment. It is a long-lived secret and follows the customer’s existing secret-management discipline. Keys live server-side — inside the customer backend or workflow service runtime — and are read at startup from a secret manager or secure runtime configuration (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, an environment-injected secret store, or equivalent). They never appear inside frontend bundles, mobile binaries, or any artifact a non-trusted runtime can read. Sandbox and Production keys are independent. Each environment carries its own credential, and the two are never shared. If exposure is suspected, the key is rotated immediately and the records captured during the exposure window are reviewed. And keys never appear in logs. Application logs, APM events, and error trackers redact credentials before any line ships to long-term log infrastructure. For deeper customer-side guidance on credential storage, rotation discipline, and per-environment placement, see the [API Key Placement and Secret Storage](/resources/api-key-placement-and-secret-storage) architecture page. ## Operational context requirements Operational context is the set of stable, customer-recognizable identifiers reviewers will use to retrieve the retained decision record later. Choosing it well is the single highest-leverage capture-side decision for retrieval-oriented workflows. - claimId — insurance claim handling, coverage review, appeals. - encounterId — healthcare encounter, intake, post-encounter workflows. - transactionId — financial transaction, dispute, chargeback workflows. - reviewCaseId — internal review, quality assurance, audit sampling workflows. - escalationId — support, complaint, SIU, or fraud escalation handling. - policyId — insurance policy, account-bound coverage decisions, underwriting. ### Safe example ```json { "workflowId": "claims-review", "operationalContext": { "claimId": "CLM-220145", "policyId": "POL-99214", "reviewCaseId": "REV-4402" } } ``` - Operational context is for retrieval later — not for dumping full records, sensitive payloads, or fields that do not survive review. - Choose stable business identifiers your reviewers already use day-to-day. Avoid transient request IDs, generated tokens, or values that change between releases. - Avoid temporary or placeholder values (CLM-TEST-1, FAKE-123, debug strings) in Production payloads — they make later retrieval painful. - Keep the operational-context payload minimal. The goal is retrieval, not duplication of the customer's authoritative system of record. For deeper customer-side guidance on mapping existing business identifiers onto operational context, see the [Operational Context Mapping](/resources/operational-context-mapping) architecture page. ## Operational context vs prompt and response Operational context and AI-assisted content sit on the same record but serve different purposes. Conflating them is one of the most common shape mistakes during a first integration. Operational context (claimId, encounterId, transactionId, escalationId, ticketId, and similar) is the durable retrieval surface reviewers depend on. It is what a reviewer types into a search box, what a downstream review surface joins on, and what an audit program retrieves a record by months after the workflow ran. Prompt and response are the AI-assisted content reviewers need when inspecting a specific retained decision record. They are the body of the record, not the retrieval handle. > In governed deployments, prompt and response may be subject to the customer's field retention policy — redacted, truncated, dropped, or marked neverForward — while operational context typically remains allowed. The retrieval surface stays usable even when the body is retained sparsely. ## Environment-aware capture Verify enforces strict environment separation, and the customer-side capture surface should be environment-aware end-to-end. Sandbox keys capture Sandbox records and Production keys capture Production records — the customer backend uses each only inside the runtime that environment authorizes. Records do not move between environments. A record captured in Sandbox cannot be retrieved from Production, and vice versa. The same applies to inspection, verification, and listing — every call is scoped to the environment of the credential used. Wrong-environment retrieval is one of the most common reasons records appear missing during a first integration. Confirming the active environment before assuming a record was not captured resolves the majority of these reports. > Validate capture, retrieval, and verification in Sandbox before Production rollout. > > > > > A clean Sandbox dry-run of the full capture-and-retrieve loop — capture one record, retrieve it by operational context, inspect it, verify it — is the most reliable predictor of Production behavior. ## Retry and error handling Capture and retrieval calls should be retry-aware. The customer backend owns retry behavior, idempotency, and the customer-side observability that proves capture is healthy. Retries are bounded — a small attempt count for synchronous paths, a slightly larger bound for async workers — with exponential backoff and jitter to avoid synchronized retry waves across worker fleets. Unbounded retries against a degraded service slow recovery, increase duplicate risk, and obscure the real failure mode. Operational context is preserved across attempts: the same workflowId, the same operationalContext, the same retry key. The retry key is the customer-side idempotency anchor; reusing it across retries is what makes them idempotent on the Verify side. A timeout is treated as *uncertain*, not *failed*. Blind resubmission after a timeout can create duplicate records. The safer pattern is to retrieve by operational context first — if the record is already there, no retry is needed. And permanent customer-side errors (invalid credentials, malformed payloads) are never retried; they are returned to the caller for correction. Exact retry windows and rate-limit semantics may vary by configuration and the active published API contract. Customer workflows should not depend on specific retry timing beyond what the active contract documents. ## Logging guidance Customer-side logs around capture are valuable for troubleshooting and operational observability. The logging surface should support recovery without surfacing credentials. ### Recommended log fields - workflowId — to correlate the capture call back to the workflow that produced the record. - environment — Sandbox or Production, so log queries can be scoped per environment. - operational context reference — the primary retrieval key (for example, claimId or transactionId) used at capture time. - decisionRecordId when returned — useful when investigating capture or verification questions later. - capture outcome — success, retryable failure, non-retryable failure, or timeout. - retry attempt count — to surface retry storms or pathological backoff behavior in customer-side observability. ### Avoid logging - API keys, bearer tokens, or any other authentication credential. - Unnecessary sensitive workflow evidence — full payloads, full prompts, or output bodies that are not required for customer-side troubleshooting. - Raw credentials — anywhere in application logs, APM events, error trackers, or third-party log infrastructure. ## Common mistakes The mistakes below are the patterns that surface most often during onboarding and Production rollout. They are listed not because they are exotic, but because they are the patterns that weaken the trust boundary or break retrieval in ways that reach reviewers months later. Walking the list before promotion is a low-cost way to find them in Sandbox. | Mistake | Why it matters | Better pattern | | --- | --- | --- | | Calling Verify from frontend code | Exposes the API key and submits AI-assisted decision context from an untrusted runtime. | Frontend and mobile apps call the customer backend, which submits to Verify on their behalf. | | Storing API keys in source code | Keys committed to source control are long-lived credential leaks even if the repository is private. | Read keys from a secret manager or secure runtime configuration at process start. | | Using a Sandbox key in a Production workflow | Records end up in Sandbox where downstream Production reviewers cannot retrieve them. | Per-environment credentials, with the runtime environment explicitly checked before the first capture call. | | Omitting operationalContext | Records cannot be retrieved later using information reviewers already know. | Always attach stable business identifiers — claimId, encounterId, transactionId, escalationId, policyId, reviewCaseId. | | Using temporary workflowId values | Renaming or regenerating workflowId across releases breaks retrieval-by-workflow. | Treat workflowId as a stable business identifier owned by the customer team — claims-review, fraud-triage, intake-summary. | | Logging secrets | Credentials in application logs become long-lived leaks reachable from log infrastructure. | Redact API keys and bearer tokens before any log line ships, and review log retention with the customer's security team. | | Retrying without duplicate awareness | Unbounded retries on uncertain timeouts can create duplicate retained decision records. | Use bounded retries with a stable retry key, and retrieve by operational context before resubmitting if capture status is uncertain. | ## How to know capture is working Once a Sandbox capture call is wired in, a small set of cross-checks confirms whether the integration is actually working end-to-end. The list below is the shortest path to that confirmation; if every item is true, capture is functioning correctly and the integration is ready for the validation pass before Production rollout. - Capture request succeeds — the customer backend submits the call without network or SDK errors. - HTTP 201 returned — the response status indicates the record was created. - decisionRecordId returned in the capture response in the dr_ format. - Record visible in Verify Console under the active environment and workspace. - Retrieval works — the record can be found by decisionRecordId and by operational context. - Verification works — calling verification on the captured record returns a verification result. - Capture policy behaves as expected — in governed deployments, the proxy log shows the matched rule and outcome. - Allowed fields appear — fields the field retention policy allows are present on the retained decision record. - Dropped fields do not appear — fields the field retention policy drops, redacts, truncates, or marks neverForward are not present on the retained decision record. - Logs contain metadata only — no prompts, responses, API keys, bearer tokens, secrets, or dropped fields appear in customer-side logs. > If all checks pass, server-side capture is functioning correctly. Move on to the validation checklist below before Production rollout. ## Validation checklist Promotion is a moment where it is easy to miss a control because the integration “just works” against a single Sandbox payload. The checklist below is a final pass that confirms both governance discipline and operational discipline hold before Production traffic begins flowing through the capture surface. Before promoting a server-side capture integration: ### Governance and policy - Governance boundary is correct for the workload — direct capture for evaluation and Sandbox, customer-owned proxy for production, governance, enterprise, and regulated workloads. - Capture decision policy has been reviewed and signed off by the customer team that owns the policy. - Field retention policy has been reviewed and signed off — allowed fields, dropped fields, redacted fields, truncated fields, and neverForward fields are all explicit and intentional. - Environment separation is confirmed end-to-end — Sandbox and Production credentials, runtimes, downstream review surfaces, and observability surfaces are all isolated. - Dropped fields are confirmed absent from retained decision records, Verify Console, and evidence reports. ### Operational discipline - API key is stored server-side in a secret manager or secure runtime configuration. - Sandbox capture succeeds — a retained decision record is recorded from the customer backend with the production-shaped payload. - The retained decision record is created with workflowId and a stable operationalContext attached at capture time. - The record can be retrieved by operational context — using the same identifiers reviewers will use day-to-day. - The verification workflow works end-to-end — calling verification on a captured record returns a verification result. - Retry behavior is bounded, backoff-aware, and idempotent — duplicate records are prevented across retries. - Customer-side logs do not expose credentials, raw bearer tokens, or unnecessary sensitive workflow evidence. - Production API key is separate from the Sandbox key — distinct credentials, distinct downstream review surfaces, distinct operational dashboards. - Operators understand the environment scope — reviewers know which environment a retrieved record belongs to before any downstream operational action. ## Related documentation The pages below cover the architectural decisions server-side capture depends on most directly: the credential placement that anchors the trust boundary, the environment discipline that scopes records, the governance proxy that holds the policies, and the deployment shape that gives all of it a home. - [Quickstart — first-time customer onboarding path.](/resources/quickstart) - [Install and Configure Verify — canonical first-time developer onboarding loop end-to-end.](/resources/install-and-configure-verify) - [Customer Integration Patterns — runtime and governance pattern selection guidance.](/resources/customer-integration-patterns) - [Configuring an AI Capture Policy — capture decision policy and field retention policy for customer-owned proxy deployments.](/resources/configuring-an-ai-capture-policy) - [Troubleshooting Verify Integrations — symptom-first reference for SDK, API, Terraform, CloudFormation, capture policy, and Console issues.](/resources/troubleshooting-verify-integrations) - [Reference Architecture: AWS — customer-side deployment topology for AWS-hosted workflows.](/resources/reference-architecture-aws) - [Verify API Reference — first-time-user API reference with the full capture, retrieval, inspection, and verification picture.](/resources/api-reference) - [Verify SDK Reference — capture SDK methods, environment-aware onboarding, and operational context guidance.](/resources/verify-sdk-reference) - [API Key Placement and Secret Storage — where Verify API keys belong and how to store them securely.](/resources/api-key-placement-and-secret-storage) - [Environment Strategy — Sandbox vs Production separation discipline across customer environments.](/resources/environment-strategy) - [Operational Context Mapping — mapping existing customer business identifiers into operational context for retrieval-oriented workflows.](/resources/operational-context-mapping) - [Customer Security Overview — broader customer-side security posture around Verify integrations.](/resources/security-overview) --- --- title: Troubleshooting Verify Integrations slug: troubleshooting-verify-integrations category: Developers retrievalTier: 3 retrievalRole: supporting canonical: false lastUpdated: 2026-08-20 href: /resources/troubleshooting-verify-integrations canonicalUrl: "https://obligra.ai/resources/troubleshooting-verify-integrations" llmTags: - llm-aligned - integration - troubleshooting - support-runbook - first-time-integration - retrieval-tier-3 - supporting-reference --- # Troubleshooting Verify Integrations _Developers_ _The vast majority of Verify integration friction surfaces in a small number of recognizable failure modes — SDK installation, environment variables, API key placement, payload shape, console visibility, Terraform or CloudFormation drift, capture policy evaluation, search and retrieval, and verification mismatches. This page exists to make those failure modes easy to recognize, easy to diagnose, and easy to resolve without escalating. In practice, every issue below has been seen at least once during a real customer integration; treating the page as a runbook rather than a reference is the fastest path to a green Sandbox loop or a working Production rollout._ ## Before you troubleshoot Most first-integration issues are resolved by confirming a handful of preflight checks. Walk down this list before opening any section below. - Confirm the active Verify environment (Sandbox or Production). - Confirm the API key belongs to that environment. - Confirm you are signed into the correct Verify Console user and workspace. - Confirm the backend or customer-owned proxy is using the intended Verify API base URL. - Confirm your AWS CLI profile points to the intended AWS account. - Confirm you received (or did not receive) a decisionRecordId in the capture response. > Environment and credential mismatch is the single most common cause of first-integration confusion. Confirm Sandbox vs Production on the credential, the request, and the Console before looking elsewhere. ## Quick symptom lookup Scan the table below for the symptom you are seeing and jump directly to the matching section. Most first-time integration issues are resolved without reading the full guide. | Symptom | Go to | | --- | --- | | 401 Unauthorized | | | Invalid API key | | | SDK import or module errors | | | HTTP 201 but no record visible | | | Record exists but search fails | | | Verification unavailable | | | Terraform deployed to wrong account | | | CloudFormation deployment failed | | | | | | Expected field missing from record | | | CloudWatch logs appear empty | | | Unsure which deployment model to use | | ## How to know Verify is working Use this checklist to confirm a first integration is wired end-to-end. If every item below is true, the integration is working correctly. - API key created — a Sandbox API key is visible in the Verify Console and stored in the customer secret store. - Capture request succeeds — the customer backend submits a capture call without network or SDK errors. - HTTP 201 returned — the response status indicates the record was created. - decisionRecordId received — the capture response includes an ID in the dr_ format. - Record can be retrieved — calling retrieval with the same operational context returns the record. - Record appears in Verify Console — the record is listed under the active environment and workspace. - Record can be opened — workflowId, operational context, prompt, response, and model metadata are visible. - Record can be verified — calling verification returns a verification result. - Activity history reflects the workflow — capture, retrieval, and verification events are listed for the record. - Capture policy behaves as expected — in customer-owned proxy deployments, the proxy log shows the matched rule and outcome. - CloudWatch logs contain metadata only — no prompts, responses, API keys, bearer tokens, secrets, or dropped fields appear in logs. > If all checks pass, the integration is working correctly. Move on to a Production readiness review before connecting real workflows. ## Environment mismatch reference Environment mismatches are one of the most common causes of “the record does not exist” reports. The matrix below shows the four common combinations and the result a customer will observe. | Capture environment | Console environment | Expected result | | --- | --- | --- | | Sandbox | Sandbox | Works | | Production | Production | Works | | Sandbox | Production | Record appears missing | | Production | Sandbox | Record appears missing | Always verify: - API key environment — Sandbox keys are not valid in Production, and Production keys are not valid in Sandbox. - Console environment — confirm the environment selector in the Verify Console matches the capture environment. - Deployment environment — confirm the customer backend or proxy is using the API base URL for the intended environment. ## Example successful flow The flow below is the expected end-to-end customer workflow. Use it as a reference baseline when comparing observed behavior against working behavior. ```text 1. Capture request submitted from the customer backend 2. Capture response returned: { "status": "recorded", "decisionRecordId": "dr_6518ca85-ee42-449c-aa28-702a6c1b0ed7" } 3. Retrieve the record by decisionRecordId or by operational context 4. Open the record in the Verify Console under the active environment 5. Run verification on the record 6. Verification returns a result and the record is review-ready ``` If the observed flow diverges from any step above, jump to the matching section in [Quick symptom lookup](#quick-symptom-lookup) . ## SDK installation issues ### Issue: Cannot use import statement outside a module Symptom: ```text SyntaxError: Cannot use import statement outside a module ``` Cause: a default CommonJS Node project was created with `npm init -y` but the example uses ESM `import` syntax. ### Resolution **Option A.** Rename the example file from `.js` to `.mjs` . **Option B.** Add the following to `package.json` : ```json { "type": "module" } ``` CommonJS users should use the documented CommonJS import pattern from the SDK Reference if supported by the SDK release in use. ## Required environment variables ### Issue: Missing VERIFY_BASE_URL Symptoms: - SDK startup failure - Failed URL parsing - Network failure - Unexpected 404 Cause: the API key was configured but the Verify API base URL was not. ### Resolution Set both variables in the customer backend or proxy runtime: ```bash VERIFY_BASE_URL= VERIFY_API_KEY= ``` The base URL must match the intended Verify environment and deployment path. Sandbox and Production may have different base URLs — use the one shown in the Verify Console for the active environment. ## API key issues ### Issue: Invalid API key Symptoms: - 401 Unauthorized - invalid_api_key - Capture rejected Common causes: - Using only the key prefix instead of the full key value. - Missing the secret portion of the key. - Using a revoked key. - Using a key from the wrong environment (Sandbox key against Production, or vice versa). - Pasting leading or trailing whitespace into the value. - Key was accidentally exposed and has since been rotated. **Resolution.** Use the full key value shown at creation time. If the secret was lost, generate a new key. ### Issue: API key secret was lost API key secrets are shown once at creation time. Verify cannot display the secret again after that. **Resolution.** - Generate a new API key from the Verify Console. - Update the customer secret store with the new value. - Redeploy or restart the customer backend or proxy so the new value is loaded. - Revoke the old key if it is no longer needed or if exposure is suspected. ## Payload field issues ### Issue: `output` does not work Symptoms: - Model output does not appear on the retained decision record. - Record was created but the response field is missing. - SDK rejects an unsupported field. Cause: the validated customer-facing capture model uses `prompt` and `response` , not `output` , `result` , `completion` , `answer` , or `generation` . ### Resolution Use the canonical capture model: ```json { "prompt": "What was sent to the model", "response": "What the model returned" } ``` > Unsupported legacy field names may be rejected by the SDK or the customer-owned proxy to avoid silent data loss. If a payload is being rejected, check that the request is using the canonical > `prompt` / > `response` field names. ## Record created but not visible in console Symptoms: - API returns HTTP 201 (or 200) with a recorded status. - decisionRecordId is returned in the capture response. - Record cannot be found in the Verify Console. Common causes: - The Console is pointed at a different backend or API environment than the capture call used. - Customer is signed into the wrong tenant, user, or workspace. - Viewing Sandbox while the record was created in Production, or vice versa. - Record was created under a different API key or environment than the active Console session. - Search filter does not include the right decisionRecordId, workflowId, or retrieval key. ### Resolution checklist - Search by the full decisionRecordId, not a fragment. - Confirm the active environment in the Console matches the environment the capture call used. - Confirm the signed-in Console user. - Confirm the workspace selector in the Console. - Confirm the API base URL used by the backend or proxy at runtime. - Confirm the capture response actually returned status: recorded — not just network success. ## Wrong AWS account deployment Symptoms: - Terraform or CloudFormation deploys successfully. - Resources exist. - But they were created in the wrong AWS account. Cause: the AWS CLI profile in use points to a different account than the intended target. ### Resolution Before `terraform plan`, `terraform apply`, or any CloudFormation deploy, always run: ```bash aws sts get-caller-identity --profile ``` Confirm the returned account ID is the intended customer account before proceeding. > For customer-owned proxy validation, deploy into the customer-owned AWS account — not a Verify-side workload account. The customer-owned proxy is the governance boundary and must live inside the customer's trust boundary. ## CloudFormation issues ### Issue: CAPABILITY_NAMED_IAM required Symptom: CloudFormation deployment fails when creating named IAM resources. ### Resolution Deploy with the required capability: ```bash aws cloudformation deploy \ --template-file