Contract-Safe Persona CI

Overview

Keep the required CI gate deterministic and secret-minimal. Offline fixtures validate JSON:API, version, idempotency, webhook HMAC, replay, and unknown additions; an optional protected sandbox job proves connectivity without making production a test dependency.

Prerequisites

• Repository test conventions and required status names
• Redacted signed fixtures for REST and webhook contracts
• Protected sandbox secret scope and synthetic test identities

Instructions

Step 1: Define the offline denominator

List parsers, commands, event transitions, security checks, error envelopes, pagination, and compatible-addition cases that must run on every change.

Step 2: Pin contract provenance

Record source URLs, retrieval date, split fingerprints, API version, template context, and redaction method for every fixture.

Step 3: Test mutations safely

Assert operation IDs, idempotency-key reuse only with identical parameters, timeout reconciliation, and no automatic duplicate inquiry.

Step 4: Test webhook adversaries

Cover modified raw body, stale timestamp, multiple v1 candidates, constant-time comparison, duplicates, reordering, and unknown event types.

Step 5: Isolate the sandbox smoke lane

Run only for trusted branches, use a sandbox key, create a unique synthetic inquiry, cap calls, and retain redacted evidence.

Step 6: Fail closed on leaks and drift

Scan fixtures and logs for key, token, signature, PII, and wrong-host patterns; make unexplained contract drift fail the gate.

Authentication

Required offline tests use no live credential. The optional protected job uses only a sandbox bearer key and sandbox webhook secret supplied by the CI secret store.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Required offline contract-test suite
• Protected optional sandbox-smoke workflow
• Fixture provenance, drift, and redaction receipts

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

A pull request adds an unknown verification type fixture and proves the mapper routes it to review. The trusted-branch job then c…

Persona API and Inquiry Failure Triage

Overview

Diagnose from the outer boundary inward: environment and credentials, request contract, resource lifecycle, session state, webhook authenticity, then provider limits. Preserve the original status and request evidence while keeping identity data out of logs.

Prerequisites

• Timestamp, environment, endpoint, status, and provider request identifier
• Redacted request fingerprint and relevant inquiry or event ID
• Access to current Dashboard configuration and application logs

Instructions

Step 1: Freeze the evidence

Record UTC time, method, canonical host and path, API version, status, request ID, idempotency key hash, and response-body hash.

Step 2: Check environment and auth

Confirm api.withpersona.com, the target environment, key state, permissions, and explicit version. A 401 is not fixed by printing or widening the key.

Step 3: Validate the request envelope

Check JSON:API shape, template selector, content headers, account auto-create metadata, and replay parameters.

Step 4: Reconcile lifecycle state

Read the inquiry before retrying a create, resume, or transition. Distinguish pending, terminal, redacted, and unavailable resources.

Step 5: Verify event intake

Use raw bytes, timestamp-plus-dot-plus-body HMAC, all v1 candidates, constant-time compare, event-ID dedupe, and creation-time ordering.

Step 6: Respect limit signals

Read live RateLimit-* and Quota-* headers and Dashboard product quotas. On 429, reduce the responsible lane and use bounded backoff.

Authentication

Authenticate REST diagnostics with the correct environment bearer key and webhook diagnostics with the endpoint’s signing secret. Redact both before creating a ticket or debug bundle.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Ranked root-cause hypothesis with evidence
• Safe retry, reconciliation, or manual-review action
• Redacted escalation packet and unresolved risks

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

A create call times out and its replay returns an …

Account-Linked Persona Inquiry and Session Lifecycle

Overview

Model the inquiry as a durable server-side workflow. Link the customer reference during supported account auto-creation, issue sessions only when a client needs one, and never assume resuming is harmless or unlimited.

Prerequisites

• Approved inquiry template and account-linkage policy
• Durable mapping from internal subject to Persona account and inquiry IDs
• Session-token delivery and expiration controls

Instructions

Step 1: Resolve the subject

Look up the internal subject and existing Persona account or active inquiry. Prevent concurrent duplicate creates with a subject-scoped operation lock.

Step 2: Create the inquiry

POST with one template selector, meta.auto-create-account-reference-id when needed, and a durable idempotency key. Optionally request an initial inquiry session.

Step 3: Deliver the session safely

Read meta['session-token'], bind it to the intended subject and client, redact it from logs, and apply an application-side expiration and single-delivery policy.

Step 4: Observe lifecycle events

Use verified webhooks as the primary signal and GET reconciliation as a recovery path. Persist Persona event IDs and creation times.

Step 5: Resume only on demand

For an eligible pending inquiry, call /inquiries/:id/resume and read meta.session-token. Avoid eager resume because an inquiry has a default maximum of 25 sessions.

Step 6: Close the domain decision

Map observed inquiry and verification evidence into a separately reviewed business decision. Keep retry, manual review, and terminal states explicit.

Authentication

Server-side lifecycle calls use the environment bearer key and dated API version. Inquiry session tokens are short-lived client capabilities and must not be treated as API keys or logged.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Subject-to-account-to-inquiry lineage
• Session issuance and resume ledger
• Observed lifecycle and domain-decision receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Exampl…

Persona Verification Evidence and Decision Boundary

Overview

Separate Persona verification lifecycle evidence from the application’s approve, reject, or review decision. Government ID, phone, selfie, document, and database verification types can evolve; the integration must tolerate unfamiliar types and values.

Prerequisites

• Inquiry ID with authorized access
• Versioned business decision policy and manual-review owner
• PII-minimized mapping for needed verification attributes

Instructions

Step 1: Read authoritative resources

Fetch the inquiry and related verification resources under the pinned API version. Record IDs, types, statuses, checks, and timestamps without copying unnecessary PII.

Step 2: Validate completeness

Determine which verification types the template and policy require. Missing evidence is unknown or incomplete, not a silent pass.

Step 3: Normalize conservatively

Map known provider states to internal evidence states and preserve unknown types or values for review. Never fabricate check enums.

Step 4: Apply the policy boundary

Evaluate provider evidence through the versioned internal policy. Record the policy version and reasons independently of Persona’s status.

Step 5: Handle later changes

Accept verified webhook updates and reconcile the resource before changing the decision. Guard terminal decisions against stale or out-of-order events.

Step 6: Produce an auditable receipt

Retain resource IDs, redacted evidence facts, event IDs, policy version, decision, reviewer, and appeal or retry route.

Authentication

Use a service bearer key limited to the correct Persona environment. Authorization to retrieve a verification does not authorize broad storage or display of its PII.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Normalized verification-evidence set
• Versioned business decision with explicit unknowns
• Manual-review and audit receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

A government-ID verification is passed but a required selfie resource is absent. The evidence mapper records one pass and one missin…

Persona Verification Policy and Duplicate-Control Review

Overview

Do not invent price tables or skip required identity evidence. Cost work begins with the business policy and current provider commercial terms, then eliminates accidental duplicate inquiries, unnecessary sessions, polling, and avoidable production testing.

Prerequisites

• Current contract or authorized Dashboard usage data
• Versioned verification and manual-review policy
• Inquiry, session, retry, template, and product-quota metrics

Instructions

Step 1: Establish authority

Record billing period, environment, contract source, template versions, verification products, and finance or compliance owner. Treat public examples as non-binding.

Step 2: Measure workflow demand

Count unique subjects, inquiries, sessions, verification types, retries, abandoned flows, duplicates, manual reviews, and product-quota consumption.

Step 3: Find accidental duplication

Join internal operation IDs, account references, inquiry IDs, and idempotency evidence. Quantify creates caused by timeouts, races, and client retries.

Step 4: Review template policy

Compare each verification type with the approved risk tier and regulatory requirement. Changes to evidence requirements need compliance and product approval.

Step 5: Shift testing to sandbox

Use forced sandbox pass and fail for development and CI because sandbox performs no real checks and has no usage charges.

Step 6: Implement and verify

Add subject locks, idempotency, event-driven reconciliation, and observability; compare cost and risk indicators before wider rollout.

Authentication

Cost analysis uses authorized aggregate Dashboard or billing access and minimally scoped Persona API access. Never export customer PII into a finance worksheet.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Measured cost-driver and duplicate-inquiry inventory
• Policy-preserving optimization proposals with owners
• Before/after usage, risk, approval, and rollback receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

Analysis finds duplicate inquiries after PO…

Redacted Persona Diagnostic Manifest

Overview

A useful Persona escalation bundle proves environment, request contract, lifecycle, and event handling while excluding API keys, session tokens, webhook secrets, raw identity documents, and unneeded customer attributes.

Prerequisites

• Incident ID, UTC window, affected environment, and authorized investigator
• Known inquiry, account, verification, request, or event identifiers
• Approved redaction and secure-transfer policy

Instructions

Step 1: Declare scope

Record incident owner, start and end time, affected service, environment, symptom, and collection authorization.

Step 2: Collect contract evidence

Capture canonical endpoint, method, API version, status, request ID, safe response headers, deployment SHA, and template IDs.

Step 3: Collect lifecycle evidence

Record only resource IDs, types, statuses, and timestamps needed to reconstruct inquiry and verification transitions.

Step 4: Collect webhook evidence

Include endpoint ID, event ID and type, delivery time, signature-verification outcome, dedupe result, and raw-body hash—not the secret or full payload.

Step 5: Build the redaction manifest

List every omitted or transformed field, token, document, image, address, birth date, and customer attribute. Scan the bundle before export.

Step 6: Seal and transfer

Hash each artifact and the manifest, apply least-privilege access and retention, and record recipient, transfer channel, and deletion date.

Authentication

Use authorized read-only access where possible. Never place bearer keys, Persona-Signature secrets, inquiry session tokens, or signed URLs in the bundle.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Redaction manifest and artifact index
• Chronological request, resource, and webhook evidence
• Hashes, custody, retention, and escalation receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

A bundle contains a deployment SHA, endpoint and API version, inquiry ID, three status timestamps, two event IDs, signature verdicts, request IDs, and artifact hashes. It contains …

Persona Integration Release and Rollback

Overview

Deploy code, API version, templates, secrets, event consumers, and domain policy as one reviewed compatibility boundary. Rollback must preserve queued events and understand data already written by the new release.

Prerequisites

• Immutable artifact and deployment target
• Versioned configuration and secret references
• Database, queue, webhook, canary, and rollback ownership

Instructions

Step 1: Build the release manifest

Record artifact digest, API version, template IDs, endpoint IDs, schema versions, flags, secret generations, and approved migrations.

Step 2: Check compatibility

Prove old and new workers can read queued events and stored evidence across the rollout window. Expand schemas before using new fields.

Step 3: Stage secrets safely

Bind environment-specific bearer and webhook secrets through the platform secret store. Support bounded overlap for rotations.

Step 4: Canary a narrow cohort

Observe REST errors, inquiry lifecycle, signature failures, duplicates, queue lag, decisions, latency, rate headroom, and product quotas.

Step 5: Promote against thresholds

Increase traffic only while evidence remains within the declared error budget. Stop automatically on security, decision, or data-integrity failure.

Step 6: Rollback without event loss

Restore the previous artifact and configuration, keep compatible consumers running, reconcile in-flight POSTs and inquiries, and replay the durable queue.

Authentication

Deployment injects secret references, never literal values. A production artifact must be incapable of falling back to a sandbox key or accepting an unsigned webhook.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Immutable release and configuration manifest
• Canary indicators and promotion decisions
• Rollback, queue replay, and reconciliation receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

A canary reveals the new worker rejects an added event type. Promotion stops, the queue retains deliveries, the old compatible consumer resumes, and the team fixes the tolerant …

Persona Sandbox Inquiry Smoke Test

Overview

Prove the minimum create-and-read path in sandbox while keeping identity verification, account linkage, and session issuance explicit. A successful API response proves transport and contract compatibility, not that a person passed verification.

Prerequisites

• A sandbox API key and a reviewed dated API version
• An enabled sandbox inquiry template ID
• Synthetic test identity data and a durable unique operation ID

Instructions

Step 1: Choose the create contract

Use exactly one of inquiry-template-id, inquiry-template-version-id, or the supported template selector. Prefer the stable template ID unless a controlled test intentionally pins a version.

Step 2: Create replay-safe intent

Generate an Idempotency-Key from the operation ID, not a person or reference ID. Persist the request fingerprint before sending the POST.

Step 3: Link the account deliberately

When auto-creating an account, use meta.auto-create-account-reference-id; do not revive deprecated request reference-id guidance. Use meta.auto-create-inquiry-session only when the client needs an immediate session.

Step 4: Inspect the JSON:API result

Verify data.type, inquiry ID, status, template relationship, and optional meta['session-token']. Treat new fields and types as compatible additions.

Step 5: Read and dispose

GET the inquiry, compare its ID and status, then retain a redacted receipt. Never claim pass, fail, or completion unless the observed inquiry and verification states support it.

Authentication

Use the sandbox bearer API key against https://api.withpersona.com/api/v1 with the explicitly reviewed Persona-Version. Keep any session token server-side until delivered to the intended client through a protected channel.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• One redacted create-request fingerprint and inquiry ID
• Observed inquiry status and optional session-token disposition
• Pass/fail smoke-test receipt separated from identity outcome

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry se…

Persona Environment and Least-Privilege API Key Setup

Overview

Establish an explicit environment boundary before any identity workflow. Persona API keys are environment-specific, may carry different configured API versions, and must reach https://api.withpersona.com/api/v1; a credential check must not create or mutate an inquiry.

Prerequisites

• Persona Dashboard access authorized for the target environment
• A named service owner, secret store, and rotation window
• The approved dated Persona API version; current documentation shows 2025-12-08

Instructions

Step 1: Inventory the boundary

Record sandbox or production, owning service, inquiry template, API-key permissions, configured API version, and secret-store location. Never infer environment from an untrusted request.

Step 2: Create and store the key

Create the narrowest key supported by the Dashboard. Put the value in the deployment secret store, expose it only as PERSONA_API_KEY, and retain only the key name and final four characters in receipts.

Step 3: Pin request metadata

Set the base URL to https://api.withpersona.com/api/v1. Send Authorization: Bearer ..., Persona-Version: 2025-12-08 or the reviewed target version, Accept: application/json, and Content-Type: application/json for bodies.

Step 4: Run a read-only probe

List one inquiry or call another approved read endpoint. Capture status, response request identifier, rate-limit headers, environment, and API version without storing response PII.

Step 5: Prove separation and rotation

Confirm sandbox and production secrets cannot be swapped by configuration fallback. Exercise dual-secret rollout, old-key revocation, and rollback in sandbox before production.

Authentication

Persona REST authentication uses an environment-scoped API key as a bearer token. The Persona-Version request header overrides the version configured on that key for the request, so pin it deliberately and test each key independently.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Environment-and-service credential inventory
• Redacted read-only connectivity receipt
• Rotation, revocation, and rollback procedure

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint…

Deterministic Persona Sandbox and Webhook Loop

Overview

Build the local loop around Persona sandbox behavior and captured contract fixtures, not around calls to production. Sandbox performs no real verification, supports forced pass or fail paths, and incurs no usage charges.

Prerequisites

• Sandbox-only API key and template
• HTTPS-capable webhook tunnel or local fixture runner
• Synthetic identities and a secret-safe fixture directory

Instructions

Step 1: Declare the scenario

Name the template, forced outcome, inquiry state, expected event type, API version, and cleanup disposition.

Step 2: Create with an operation key

Create a sandbox inquiry using a unique Idempotency-Key. Persist IDs separately from synthetic payloads.

Step 3: Exercise the client path

Use the supported sandbox flow to force pass or fail. Do not encode sandbox-only controls into production request code.

Step 4: Capture raw webhook bytes

Save headers and raw body before parsing, redact PII, and preserve duplicate deliveries and deliberately reordered fixtures.

Step 5: Replay deterministically

Verify HMAC against raw bytes, deduplicate by event ID, order business processing by data.attributes.created-at, and assert the terminal local state.

Step 6: Reset without hiding drift

Delete only generated local artifacts through the project’s approved cleanup path; retain the contract fingerprint and test receipt.

Authentication

Use a sandbox bearer key for REST requests and a separate sandbox webhook secret for HMAC verification. Never expose either value in a tunnel URL, fixture, console log, or committed .env file.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Named sandbox scenario and synthetic inquiry receipt
• Redacted raw webhook fixture set
• Replay, duplicate, ordering, and terminal-state assertions

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

The government-id-fail scenario creates a sandbox inquiry, forces failure, captures two deliveries of the same event, replays them out of order, and proves exactly one …

Event-Driven Persona Inquiry Reconciliation

Overview

Optimize the application around authentic webhook events and bounded GET reconciliation rather than parallel polling or speculative session creation. Measure customer latency, queue lag, rate headroom, and decision freshness separately.

Prerequisites

• Latency SLO and volume by workflow
• Current traces for API calls, webhook receipt, queueing, and decisions
• Rate and quota header telemetry plus failure budget

Instructions

Step 1: Build the latency model

Measure inquiry create, client start, verification progress, provider event creation, delivery, queue delay, reconciliation, and domain decision.

Step 2: Remove polling from the hot path

Use verified webhooks as the primary notification. Keep bounded polling only for recovery and customer-visible refresh with jitter and stop conditions.

Step 3: Partition safely

Process unrelated accounts or inquiries concurrently while serializing consequential transitions per subject or inquiry.

Step 4: Avoid session churn

Create or resume an inquiry session only when a client needs it; track issuance and prevent retries from consuming the default session allowance.

Step 5: Cache only stable metadata

Cache template and non-sensitive configuration with versioned invalidation. Do not cache bearer credentials, session tokens, or stale identity decisions.

Step 6: Tune from evidence

Adjust worker count, batch size, timeout, and reconciliation interval while protecting RateLimit-*, Quota-*, error, and stale-decision thresholds.

Authentication

Performance work must preserve bearer-key isolation, raw webhook HMAC verification, and session-token confidentiality. Bypassing authentication or reconciliation is not an optimization.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• End-to-end latency and queue model
• Polling-removal and concurrency plan
• Before/after SLO, limit headroom, correctness, and rollback receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

The service replaces five-second polling with verified events and a …

Persona Production Readiness Gate

Overview

A production key and passing happy path are not enough. The gate must prove environment isolation, template governance, API-version compatibility, authentic replay-safe webhooks, quota behavior, privacy controls, manual review, rollback, and accountable approval.

Prerequisites

• Immutable release SHA and production architecture
• Named security, privacy, compliance, product, and operations approvers
• Sandbox evidence matching the intended production configuration

Instructions

Step 1: Freeze release inputs

Record code SHA, API version, templates and versions, endpoint IDs, domains, environment, feature flags, and migration plan.

Step 2: Verify access and privacy

Prove least-privilege keys, secret rotation, PII minimization, retention, access logging, customer rights, redaction governance, and incident response.

Step 3: Exercise identity paths

Run synthetic pass, fail, retry, abandon, resume, unknown-verification, duplicate-customer, and manual-review scenarios.

Step 4: Prove event reliability

Verify raw-body HMAC, rotation candidates, duplicate delivery, out-of-order delivery, queue recovery, dead-letter replay, and GET reconciliation.

Step 5: Test limits and failures

Exercise 429 handling, product-quota exhaustion, provider timeout, ambiguous POST, dependency outage, and degraded manual path.

Step 6: Approve release and rollback

Require named approvals, deploy a narrow cohort, watch defined indicators, and demonstrate rollback without losing authoritative events or decisions.

Authentication

Production readiness requires production credentials to remain in the production secret boundary. Tests should prove bindings and permissions without exporting their values.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Pass/fail gate matrix with linked evidence
• Named exceptions, owners, expiry dates, and residual risk
• Release, observation, rollback, and final approval receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

The release stays blocked because the happy path passes but duplicate webhoo…

Persona Environment Limit and Product Quota Controller

Overview

Replace invented fixed tables with two current signals: environment request limits and product-specific quotas. Production environments default to 300 requests per minute in current documentation, but Dashboard configuration and response headers govern the running integration.

Prerequisites

• Endpoint and operation inventory with expected volume
• Current environment limits and product quotas from the Dashboard
• Durable operation, retry, and reconciliation state

Instructions

Step 1: Classify work

Separate reads, idempotent POSTs, session operations, reconciliation, and product-consuming verification work. Assign independent worker lanes.

Step 2: Read live signals

Capture RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Quota-Limit, Quota-Remaining, and Quota-Reset where returned. Do not assume every endpoint exposes identical values.

Step 3: Budget below the boundary

Use token buckets per environment and constrained product. Persona recommends throttling when fewer than 15 percent of requests remain.

Step 4: Back off on 429

Honor reset or retry guidance. Where no more specific instruction exists, use the documented exponential sequence of 5, 10, 20, and 40 seconds with jitter and a finite budget.

Step 5: Protect mutations

Use Idempotency-Key on POST and persist identical parameters. After timeout or throttle ambiguity, reconcile resource state before retry.

Step 6: Escalate quota exhaustion

Pause only the affected lane, surface renewal time and business impact, and require approval before changing a paid product or verification policy.

Authentication

Rate-control workers use the same environment-scoped bearer authentication and dated API version as the guarded request. Telemetry may record header values but never the bearer key or PII payload.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Per-environment and per-product control policy
• Live header, retry, and reconciliation telemetry
• Quota-exhaustion escalation and capacity receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys,…

Account-Linked KYC Control Plane with Persona

Overview

Put Persona behind a server-side identity orchestration boundary. The application owns subject identity, operation idempotency, policy and decisions; Persona owns inquiry and verification resources; authenticated events plus reconciliation connect the two.

Prerequisites

• System context, data classification, and threat model
• Business and regulatory decision policy
• Availability, latency, retention, residency, and recovery requirements

Instructions

Step 1: Draw trust boundaries

Separate client, application API, orchestration service, secret store, Persona REST API, embedded inquiry flow, webhook edge, durable queue, decision engine, and reviewer console.

Step 2: Define authoritative identifiers

Map internal subject to Persona account and inquiry IDs. Store operation IDs and event IDs under uniqueness constraints; do not make PII the join key.

Step 3: Design commands and sessions

Create inquiries with durable idempotency and supported account-auto-create metadata. Issue or resume sessions only through authenticated subject ownership.

Step 4: Design event intake

Terminate HTTPS, retain raw bytes, verify timestamped HMAC, persist before acknowledgement, deduplicate, order by provider creation time, and tolerate unknown event types.

Step 5: Separate evidence from decision

Normalize verification resources conservatively, then apply a versioned internal policy with explicit review and appeal paths.

Step 6: Engineer recovery and privacy

Use durable queues, GET reconciliation, bounded retries, environment and quota controls, data minimization, retention, irreversible-redaction governance, and tested rollback.

Authentication

The server-side REST boundary owns environment bearer keys; the webhook edge owns signing secrets; the client receives only its inquiry session token. No credential crosses those roles.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Trust and data-flow architecture
• Identifier, command, event, evidence, and decision contracts
• Failure, security, privacy, capacity, rollback, and audit controls

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session…

Typed Persona REST Adapter and JSON:API Envelope

Overview

Keep transport, Persona resource envelopes, and domain decisions separate. The adapter should preserve raw identifiers and metadata, tolerate new resources and fields, and expose explicit mutation evidence rather than flattening every response into a brittle model.

Prerequisites

• Endpoint inventory and approved API version
• Language runtime with HTTP, JSON, and constant-time comparison support
• Domain boundary defining what may contain PII

Instructions

Step 1: Define the transport core

Centralize the API base, bearer header, dated version, timeouts, request IDs, and safe telemetry. Do not retry mutations blindly.

Step 2: Model JSON:API generically

Represent data, type, id, attributes, relationships, included, meta, links, and structured errors before adding endpoint-specific views.

Step 3: Preserve compatible additions

Treat unknown fields, resource types, event types, and array order changes as data to preserve or ignore safely, not parse failures.

Step 4: Separate command from query

Require an operation ID and Idempotency-Key for POST commands. Queries may use bounded retries; commands reconcile observed state after ambiguity.

Step 5: Normalize evidence, not identity

Return status, request ID, rate and quota headers, resource ID, and a redacted envelope hash. Keep customer attributes behind the domain privacy boundary.

Step 6: Test with contract fixtures

Cover errors, pagination, unknown fields, multiple verification types, session metadata, throttling, and ambiguous POST outcomes.

Authentication

Inject the environment-scoped bearer key at the transport boundary and pin Persona-Version per request. Callers must never pass raw credentials or select an arbitrary host.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Typed transport and JSON:API envelope interfaces
• Mutation command and read-query contracts
• Compatibility and redaction test matrix

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documen…

Persona PII, Key, Session, and Webhook Controls

Overview

Treat the integration as a high-sensitivity identity boundary. Separate server API keys, short-lived inquiry session tokens, and webhook secrets; minimize collected PII; authenticate every event; and make destructive redaction an explicit governed operation.

Prerequisites

• Data-flow and threat model for the Persona integration
• Owners for credentials, privacy, incidents, retention, and redaction
• Approved environment, template, webhook, and access-control inventory

Instructions

Step 1: Classify secrets and data

Inventory bearer keys, webhook secrets, session tokens, identity attributes, documents, images, logs, and derived decisions with owners and retention.

Step 2: Enforce environment isolation

Use distinct secret scopes, endpoints, templates, and access policies for sandbox and production. Deny production data in developer fixtures.

Step 3: Minimize privilege and exposure

Restrict keys and operator roles, keep Persona calls server-side, redact headers and bodies, and prevent session tokens from analytics or URLs.

Step 4: Authenticate raw events

Parse Persona-Signature, compute SHA-256 HMAC over timestamp + '.' + rawBody, compare all v1 candidates in constant time, and enforce a reviewed timestamp tolerance.

Step 5: Make processing replay-safe

Deduplicate event IDs and order business transitions by provider created-at, because deliveries may repeat or arrive out of order.

Step 6: Govern redaction

Require subject, resource, authorization, impact preview, child-resource expectations, and evidence before invoking redaction. It cannot be undone and child redaction is asynchronous.

Authentication

REST uses an environment bearer API key; event intake uses the endpoint webhook secret; browser flows receive only the intended inquiry session token. These credentials are not interchangeable.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Credential and sensitive-data inventory
• Webhook authenticity and replay-control design
• Retention, redaction, rotation, incident, and rollback controls

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer …

Dated Persona API Version Migration

Overview

Treat Persona-Version as a contract migration. Because the request header overrides the key’s configured version and compatible releases can add or reorder data, migrate parsers, webhook handling, and operational evidence together.

Prerequisites

• Source and target dated API versions
• Endpoint, resource, event, and consumer inventory
• Representative redacted fixtures plus a reversible rollout mechanism

Instructions

Step 1: Freeze the baseline

Record API-key configured versions, explicit headers, endpoints, templates, response hashes, events, dashboards, and consumer assumptions.

Step 2: Read the provider delta

Map documented breaking and compatible changes to each request, JSON:API mapper, event handler, policy rule, test, and data export.

Step 3: Harden for additions

Make parsers tolerate new resources, fields, types, event types, and array ordering before switching the header.

Step 4: Build dual-version fixtures

Capture or synthesize equivalent source and target responses for success, error, pagination, inquiry sessions, verifications, and webhooks.

Step 5: Canary the explicit header

Send the target Persona-Version for a bounded cohort and compare transport, resource, event, decision, latency, and quota metrics.

Step 6: Promote with rollback

Change the explicit header and key configuration deliberately, retain source-version compatibility during the observation window, and document the rollback trigger.

Authentication

Test source and target versions with appropriately scoped keys. The explicit request header is authoritative for that request, so accidental fallback to a key default is a gate failure.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Version delta and affected-consumer inventory
• Dual-version fixture and canary comparison
• Promotion, observation, rollback, and retirement receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

A parser that assumes a closed verification-type enum is changed to preserve unknown values before the canary. The target…

Authentic and Idempotent Persona Event Intake

Overview

A webhook is an untrusted delivery until its signature passes. Persona may deliver duplicates or events out of order, so authenticity, durable receipt, idempotency, event-time ordering, and resource reconciliation are distinct steps.

Prerequisites

• HTTPS endpoint retaining exact raw request bytes
• Persona webhook secret with rotation metadata
• Durable unique event store and reconciliation worker

Instructions

Step 1: Capture before parsing

Read the exact raw bytes and Persona-Signature header. Enforce size, method, content-type, and timestamp policy before business work.

Step 2: Parse signature candidates

Extract t and every v1 value. Reject malformed or missing components; retain only redacted diagnostic metadata.

Step 3: Compute and compare

Compute HMAC-SHA256 with the webhook secret over t + '.' + rawBody. Compare against every v1 candidate in constant time to support rotation.

Step 4: Acknowledge durable receipt

After authenticity, insert the event ID and raw-body hash under a uniqueness constraint, then acknowledge quickly. Duplicate inserts are successful no-ops.

Step 5: Process in provider time

Route by event type while tolerating unknown types. Use data.attributes.created-at, not arrival order, to guard state transitions.

Step 6: Reconcile before consequential action

For approval, rejection, payout, or access changes, read the current Persona resource and apply the versioned domain policy.

Authentication

Webhook authentication uses the endpoint signing secret and the Persona-Signature HMAC protocol; it does not use the REST bearer key. Resource reconciliation uses the environment bearer key separately.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.

Output

• Signature-verification contract and test vectors
• Durable event receipt, dedupe, ordering, and routing design
• Reconciliation and business-transition receipt

Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.

Examples

During rotation a he…