{ "openapi": "3.1.0", "info": { "title": "FLINT Agent Transaction Control API", "version": "1.0.0", "description": "FLINT verifies agent authority before autonomous economic activity, issues signed verification records, accepts outcome feedback, and returns partner-safe Trust Graph reputation.", "x-guidance": "Use POST /api/x402/scan for a $0.01 x402-paid bounded pre-transaction scan of a separate intended commerce transaction. Use POST /api/x402/verify for high-assurance $0.01 x402-paid agent-authority verification after obtaining the required FLINT capability and DPoP proof. Free operations are explicitly marked with security: [].", "contact": { "name": "FLINT Support", "email": "support@flint.network", "url": "https://flint.network" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-FLINT-Proprietary" } }, "servers": [{ "url": "https://flint.network", "description": "Production" }], "security": [], "tags": [ { "name": "Verification Records", "description": "Issue and verify signed verification records." }, { "name": "Outcome Feedback", "description": "Submit transaction outcomes that seed Trust Graph reputation." }, { "name": "Trust Graph", "description": "Read partner-safe aggregate agent reputation and graph health." }, { "name": "Agent Passport", "description": "Issue, resolve, and update Agent Passports: hybrid-signed agent identity credentials with a separate mutable mandate." }, { "name": "Agent Sessions", "description": "Email OTP sign-in for agents: request and verify a one-time code, then use the returned bearer session token wherever a browser session cookie is accepted." }, { "name": "Scout Credits", "description": "Prepaid FLINT Scout scan credits: one x402 payment buys a block of scans that run without a per-call wallet signature." } ], "paths": { "/api/passport": { "post": { "x-flint-release-state": "production", "security": [], "tags": ["Agent Passport"], "operationId": "issueAgentPassport", "summary": "Issue an Agent Passport", "description": "Issues a hybrid-signed (ES256 + ML-DSA-65) Agent Passport that binds an agent to its controller and wallet. The passport signs identity only; the mandate is a separate, unsigned, mutable config. Persists the passport, seeds the Trust Graph, and returns a public resolvable id. Free and per-IP rate limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportIssueRequest" } } } }, "responses": { "200": { "description": "Passport issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/passport/{passport_id}": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Agent Passport"], "operationId": "resolveAgentPassport", "summary": "Resolve a public Agent Passport", "description": "Returns the signed passport envelope, decoded identity, current mandate, and a verification summary (signature valid, status, not expired).", "parameters": [ { "name": "passport_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^kya_" }, "description": "Passport id (kya_ prefix + ULID)." } ], "responses": { "200": { "description": "Passport resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportResponse" } } } }, "404": { "description": "Passport not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "x-flint-release-state": "production", "security": [{}, { "WorkOSOwnerSession": [] }], "tags": ["Agent Passport"], "operationId": "updateAgentMandate", "summary": "Update a mandate, manage a claim, or authorize a Shopify purchase", "description": "Dispatches on the request body's action field (default update_mandate when omitted): update_mandate (mutable mandate config), begin_claim (validate a claim token and open a pending claim), refresh_claim_token (rotate a lost or consumed claim token), issue_purchase_authorization, or issue_preflight_capability. Updating the mandate is a pure data update: it bumps the mandate version and signs nothing, so the passport signature is unchanged.", "parameters": [{ "name": "passport_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^kya_" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MandateUpdateRequest" }, { "$ref": "#/components/schemas/BeginClaimRequest" }, { "$ref": "#/components/schemas/RefreshClaimTokenRequest" }, { "$ref": "#/components/schemas/PurchaseAuthorizationRequest" } ] } } } }, "responses": { "200": { "description": "Mandate updated (signature unchanged), or a claim step (begin_claim / refresh_claim_token) completed.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MandateUpdateResponse" }, { "$ref": "#/components/schemas/BeginClaimResponse" }, { "$ref": "#/components/schemas/RefreshClaimTokenResponse" } ] } } } }, "201": { "description": "Purchase authorization issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseAuthorizationResponse" } } } }, "400": { "description": "Invalid request, such as a missing claim_token on begin_claim.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "claim_token_invalid (begin_claim with a wrong or expired token), refresh_not_authorized (refresh_claim_token with neither a valid management_token nor an authorized session), or the mandate-update owner/claim-token checks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "passport_not_found, or no_pending_claim (begin_claim / refresh_claim_token with no open claim to act on).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "passport_already_owned (begin_claim / refresh_claim_token on a passport that is already claimed), passport_revoked, or passport_frozen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "passport_superseded: this passport was replaced by a remint while it was still unclaimed. superseded_by names the replacement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many refresh_claim_token requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/verify": { "post": { "x-flint-release-state": "production", "security": [], "tags": ["Verification Records"], "operationId": "issueAuthorizationRecord", "summary": "Issue a signed verification record", "description": "Use before an AI agent initiates a payment, paid API call, checkout action, stablecoin transfer, x402 request, or delegated commercial transaction. Returns a compact JWS signed verification record.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "examples": { "agentPayment": { "summary": "Agent payment authorization", "value": { "nonce": "8b2ef62d-6ec0-4ac8-a5e4-e6d4ec447bcf", "timestamp": "2026-05-20T16:00:00.000Z", "partner_id": "sandbox_public", "merchant_reference": "invoice_123", "transaction": { "amount_display": "42.00", "asset": "USDC", "chain": "eip155:8453", "counterparty_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "declared_scope": { "max_amount_per_tx_display": "250.00", "allowed_counterparties": ["invoice_123"], "time_window_end": "2026-05-20T17:00:00.000Z" }, "agent_claim": { "agent_id": "agent_checkout_worker", "principal_hint": "skyfire", "agent_runtime_hint": "browser" } } } } } } }, "responses": { "200": { "description": "Compact JWS signed verification record", "headers": { "X-FLINT-Verdict": { "schema": { "$ref": "#/components/schemas/VerdictDecision" } }, "X-FLINT-Score": { "schema": { "type": "string" } } }, "content": { "application/jwt": { "schema": { "type": "string", "description": "Compact JWS containing the signed verification record." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/x402/scan": { "post": { "x-flint-release-state": "production", "security": [{ "X402Payment": [] }], "tags": ["Verification Records"], "operationId": "purchasePreTransactionScan", "summary": "Pay for and execute a bounded pre-transaction scan", "description": "x402 resource for autonomous buyers. The x402 payment purchases FLINT's scan service; the request body describes a separate intended commerce transaction that has not executed. Unknown callers receive bounded deterministic evaluation without external provider or model calls. A verified FLINT Agent Passport bound to the x402 payer wallet can upgrade authority evidence.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [{ "x402": {} }] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ScanRequest" }, "examples": { "agentTransaction": { "value": { "nonce": "scan-01K3J6M2F7H8Q9R0S1T2V3W4X5", "timestamp": "2026-08-25T22:00:00.000Z", "transaction": { "action": "stablecoin_transfer", "reference": "invoice_123", "chain": "eip155:8453", "token": { "symbol": "USDC", "issuer": "circle" }, "amount_display": "24.50", "counterparty_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "agent_claim": { "agent_id": "procurement-agent-7", "agent_runtime_hint": "x402_buyer", "wallet_type": "eoa" } } } } } } }, "responses": { "200": { "description": "The service payment settled and FLINT returned a signed pre-transaction decision record.", "headers": { "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" }, "X-FLINT-Score": { "$ref": "#/components/headers/FlintScore" }, "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ScanResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/X402PaymentRequired" }, "403": { "description": "The verified payment did not provide a bindable payer wallet, or a presented Passport is terminally ineligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "431": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/x402/verify": { "post": { "x-flint-release-state": "production", "security": [{ "X402Payment": [], "FlintCapability": [], "DPoP": [] }], "tags": ["Verification Records"], "operationId": "purchaseAgentAuthorityVerification", "summary": "Pay for metered agent-authority verification", "description": "High-assurance x402 lane. The unpaid challenge is bounded. A paid retry must present a request-bound FLINT capability and DPoP proof before facilitator, provider, model, or record work becomes eligible.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [{ "x402": {} }] }, "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Canonical x402 v2 payment proof on the paid retry." }, { "name": "FLINT-CAPABILITY", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Short-lived Passport-owner-issued capability bound to the exact paid request. Required when payment is presented." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Fresh caller proof bound to the capability, request, and x402 payment proof. Required when payment is presented." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402VerifyRequest" } } } }, "responses": { "200": { "description": "Payment settled and FLINT issued a signed verification record. Receipt state is reported separately and truthfully.", "headers": { "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" }, "X-FLINT-Score": { "$ref": "#/components/headers/FlintScore" }, "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402VerifyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/X402PaymentRequired" }, "403": { "description": "The paid retry failed capability, DPoP, replay, or caller-admission policy before expensive work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/x402/readiness": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Verification Records"], "operationId": "getX402Readiness", "summary": "Get non-secret x402 readiness", "description": "Returns configuration state and booleans for the high-assurance Verify lane and separately pinned marketplace scan lane. This route performs no provider call and returns no credential-derived value.", "responses": { "200": { "description": "Bounded non-secret readiness state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ReadinessResponse" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/api/x402/scout-credits": { "post": { "x-flint-release-state": "staging", "security": [{ "X402Payment": [] }], "tags": ["Scout Credits"], "operationId": "purchaseScoutCredits", "summary": "Pay for a block of prepaid Scout scan credits", "description": "x402 resource that sells 100 FLINT Scout scan credits for $1.00. Requires a session (WorkOSOwnerSession cookie or bearerAgentSession bearer token) so the credits land on an account. On settlement, credits the account, issues an fsr_ settlement receipt with purpose flint_scout_credit_topup, and returns the new balance.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.000000" }, "protocols": [{ "x402": {} }] }, "responses": { "200": { "description": "Payment settled and 100 credits were added to the caller's account.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutCreditsTopupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "No WorkOSOwnerSession cookie or bearerAgentSession token was presented; credits need an account to land on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "$ref": "#/components/responses/X402PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/account/scout-credits": { "get": { "x-flint-release-state": "staging", "security": [{ "WorkOSOwnerSession": [] }, { "bearerAgentSession": [] }], "tags": ["Scout Credits"], "operationId": "getScoutCreditsBalance", "summary": "Read the caller's Scout credit balance and recent ledger", "description": "Returns the current Scout credit balance, lifetime purchased and used totals, and the last 20 ledger entries (topup, debit, refund) for the authenticated account.", "responses": { "200": { "description": "Balance and ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutCreditsBalanceResponse" } } } }, "401": { "description": "No WorkOSOwnerSession cookie or bearerAgentSession token was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/account/scout-credits/intent": { "post": { "x-flint-release-state": "staging", "security": [{ "WorkOSOwnerSession": [] }, { "bearerAgentSession": [] }], "tags": ["Scout Credits"], "operationId": "createScoutCreditsTopupIntent", "summary": "Create a Scout credits top-up intent", "description": "Session required (WorkOSOwnerSession cookie or bearerAgentSession bearer token) so FLINT knows which account to credit before any money moves. Returns an sct_ topup_id good for 24 hours and its pay_url: POST /api/x402/scout-credits/{topup_id}, a route that needs no session to pay, so a stock x402 client's unauthenticated discovery request (awal x402 pay, for example) can settle it. Rate limited to 10 intents per rolling hour per account.", "responses": { "200": { "description": "Intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutCreditsTopupIntentResponse" } } } }, "401": { "description": "No WorkOSOwnerSession cookie or bearerAgentSession token was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/x402/scout-credits/{topup_id}": { "post": { "x-flint-release-state": "staging", "security": [{ "X402Payment": [] }], "tags": ["Scout Credits"], "operationId": "purchaseScoutCreditsTopupIntent", "summary": "Pay a Scout credits top-up intent", "description": "x402 resource that settles one Scout credits top-up intent created by POST /api/account/scout-credits/intent. No session is required or accepted here: the intent already bound topup_id to an account, which is what lets a stock x402 client with an unauthenticated discovery request (awal x402 pay , for example) pay it. Every request is gated on the intent first, before any payment work: an unknown topup_id is 404; an already-settled or expired one is 409. Idempotent on settlement: a second successful payment against an already-settled topup_id is never credited twice.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.000000" }, "protocols": [{ "x402": {} }] }, "parameters": [ { "name": "topup_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sct_[0-9A-Za-z]{20,32}$" }, "description": "Top-up intent id from POST /api/account/scout-credits/intent." } ], "responses": { "200": { "description": "Payment settled and 100 credits were added to the intent's account.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutCreditsTopupIntentSettledResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Canonical x402 v2 payment challenge, with a pay_recipe (awal, script, credits, browser) for ways to pay this exact intent. No protected or expensive work has executed.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "topup_intent_not_found: no intent exists for this topup_id, or it expired out of storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "topup_intent_already_settled or topup_intent_expired: returned before any payment work when checked up front, or after a real settlement lost a redemption race (in which case the payment settled but was not credited a second time).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/records/{record_id}/outcome": { "post": { "x-flint-release-state": "staging", "security": [{}, { "WorkOSOwnerSession": [] }, { "bearerAgentSession": [] }, { "PartnerServiceBearer": [] }], "tags": ["Outcome Feedback"], "operationId": "reportRecordOutcome", "summary": "Report what actually happened after a Scout scan", "description": "FLINT cannot stop a wallet; this is the enforce-or-attest half of the contract. Reports whether the scanned transaction executed, was held, or was cancelled. Auth is one of: a bearer or cookie session whose account owns the passport presented on the record, the anonymous caller_binding_token issued with the scan (open security, no scheme), or a partner service credential. Idempotent: the first write wins and a later write returns 409 with the existing outcome. Reporting executed or executed_despite_block after a BLOCK verdict is stored as an override, appended to the passport ledger, and alerts the passport owner through Sentinel.", "parameters": [{ "$ref": "#/components/parameters/RecordId" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeReportRequest" } } } }, "responses": { "200": { "description": "Outcome recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "No session, caller_binding_token, or partner credential was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The presented session does not own the passport bound to this record, or the caller_binding_token does not match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An outcome was already reported for this record. The existing outcome is returned unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeReportResponse" } } } } } } }, "/api/counterparty/{address}": { "get": { "x-flint-release-state": "staging", "security": [], "tags": ["Verification Records"], "operationId": "getCounterpartyScans", "summary": "Look up Scout scans that named this address as counterparty", "description": "Public, unauthenticated, rate-limited lookup. Returns bounded, newest-first, redacted evidence (no payer wallet, no nonce, no caller binding tokens) of FLINT Scout scans that named this address as the transaction counterparty, with each record's reported outcome when available.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "description": "EVM counterparty address." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_A-Za-z0-9]{1,32}$", "default": "eip155:8453" }, "description": "CAIP-2 chain identifier. Defaults to eip155:8453." } ], "responses": { "200": { "description": "Bounded, redacted scan history for this counterparty address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/x401/verify": { "post": { "x-flint-release-state": "production", "security": [{}, { "X401Proof": [] }], "tags": ["Verification Records"], "operationId": "verifyX401PrincipalPresentation", "summary": "Verify an x401 principal-identity presentation", "description": "Without PROOF-RESPONSE, returns a signed OpenID4VP proof challenge. With a valid presentation, verifies the principal, issues a signed verification record, and returns proof-result metadata.", "parameters": [ { "name": "PROOF-RESPONSE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64url-encoded x401 proof response. Omit to request a challenge." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "200": { "description": "Principal presentation verified and signed record issued.", "headers": { "PROOF-RESULT": { "$ref": "#/components/headers/X401ProofResult" }, "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" }, "X-FLINT-Score": { "$ref": "#/components/headers/FlintScore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401VerifyResponse" } } } }, "400": { "description": "Invalid request or presentation.", "headers": { "PROOF-RESULT": { "$ref": "#/components/headers/X401ProofResult" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401ProofResult" } } } }, "401": { "description": "Proof challenge required.", "headers": { "PROOF-REQUEST": { "$ref": "#/components/headers/X401ProofRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401ChallengeResponse" } } } }, "409": { "description": "The x401 verifier nonce was already used.", "headers": { "PROOF-RESULT": { "$ref": "#/components/headers/X401ProofResult" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401ProofResult" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/records/{record_id}": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Verification Records"], "operationId": "getVerificationRecord", "summary": "Retrieve a signed verification record", "description": "Returns the portable hybrid envelope by default, a bare ES256 compact JWS for format=jws, or a decoded inspection view for format=decoded. The decoded view is not itself signed.", "parameters": [ { "$ref": "#/components/parameters/RecordId" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["decoded", "jws"] }, "description": "Omit for the portable hybrid envelope." } ], "responses": { "200": { "description": "Stored record in the requested representation.", "headers": { "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" } }, "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/HybridEnvelopeWithAcknowledgments" }, { "$ref": "#/components/schemas/DecodedRecordResponse" }] } }, "application/jwt": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/records/{record_id}/acknowledge": { "post": { "x-flint-release-state": "production", "security": [], "tags": ["Verification Records"], "operationId": "acknowledgeVerificationRecord", "summary": "Attach a counterparty acknowledgment", "description": "Stores bounded counterparty acknowledgment evidence beside the immutable record. Unsupported or invalid signatures are retained as unverified claims and are never represented as cryptographically verified.", "parameters": [{ "$ref": "#/components/parameters/RecordId" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordAcknowledgmentRequest" } } } }, "responses": { "201": { "description": "Acknowledgment stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordAcknowledgmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Acknowledgment submission rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/records/schema": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Verification Records"], "operationId": "getVerificationRecordSchema", "summary": "Get the verification-record JSON Schema", "description": "Returns the canonical JSON Schema for the payload carried by a FLINT hybrid signing envelope.", "responses": { "200": { "description": "JSON Schema draft 2020-12 document.", "content": { "application/schema+json": { "schema": { "type": "object" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/api/settlement-receipts/{receipt_id}": { "get": { "x-flint-release-state": "staging", "security": [], "tags": ["Verification Records"], "operationId": "getSettlementReceipt", "summary": "Retrieve a linked x402 settlement receipt", "description": "Returns the portable purpose-separated hybrid receipt envelope by default, a bare ES256 compact JWS for format=jws, or a decoded inspection view for format=decoded.", "parameters": [ { "$ref": "#/components/parameters/SettlementReceiptId" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["decoded", "jws"] }, "description": "Omit for the portable hybrid envelope." } ], "responses": { "200": { "description": "Stored settlement receipt in the requested representation.", "headers": { "X-FLINT-Artifact-Type": { "description": "Always x402_settlement_receipt for a successful response.", "schema": { "type": "string", "const": "x402_settlement_receipt" } } }, "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/HybridEnvelope" }, { "$ref": "#/components/schemas/DecodedSettlementReceiptResponse" }] } }, "application/jwt": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/outcomes": { "post": { "x-flint-release-state": "production", "security": [{ "PartnerServiceBearer": [] }], "tags": ["Outcome Feedback"], "operationId": "submitTransactionOutcome", "summary": "Submit transaction outcome feedback", "description": "Authenticated partner callback used after a transaction completes, is disputed, or is flagged. The bearer identity must match the partner bound into the stored signed record; caller-supplied partner ids are ignored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeRequest" } } } }, "responses": { "201": { "description": "Outcome accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/graph/agent/{flint_agent_id}": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Trust Graph"], "operationId": "lookupAgentReputation", "summary": "Lookup partner-safe aggregate agent reputation", "description": "Returns partner-facing aggregate reputation for a partner-scoped FLINT agent ID. Raw runtime provider identifiers and internal signal fields are not returned.", "parameters": [ { "name": "flint_agent_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^faid_[a-f0-9]{24}$" }, "description": "Partner-scoped FLINT agent identifier." } ], "responses": { "200": { "description": "Agent reputation summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReputationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/graph/health": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Trust Graph"], "operationId": "getTrustGraphHealth", "summary": "Check Trust Graph health", "description": "Operational endpoint that checks Trust Graph configuration and connectivity.", "responses": { "200": { "description": "Trust Graph is reachable or intentionally unconfigured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphHealthResponse" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/.well-known/jwks.json": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Verification Records"], "operationId": "getJwks", "summary": "Get FLINT public signing keys", "description": "Returns the public JWKS used to verify compact JWS signed verification records.", "responses": { "200": { "description": "JSON Web Key Set", "content": { "application/json": { "schema": { "type": "object", "required": ["keys"], "properties": { "keys": { "type": "array", "items": { "type": "object" } } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/.well-known/flint.json": { "get": { "x-flint-release-state": "production", "security": [], "tags": ["Trust Graph"], "operationId": "getFlintTrustManifest", "summary": "Get FLINT Trust Manifest", "description": "Returns this domain's Trust Manifest for agent commerce authorization semantics.", "responses": { "200": { "description": "FLINT Trust Manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustManifest" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/api/account/claim": { "post": { "x-flint-release-state": "staging", "security": [{ "WorkOSOwnerSession": [] }, { "bearerAgentSession": [] }], "tags": ["Agent Passport"], "operationId": "claimPassportOwnership", "summary": "Attach an anonymously minted passport to the caller's account", "description": "Attaches an unclaimed passport to the authenticated caller's FLINT account. Two request shapes: { passport_id, claim_token } presents the one-time token from the mint's claim_url. { passport_id } alone works only when the caller's account already holds a pending-claim binding for this passport (begin_claim or refresh_claim_token while signed in, the MCP claim flow, or the flint_claim_intent cookie surviving an OTP delay). Every non-owned failure returns a distinct reason code instead of one shared error string.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/ClaimByTokenRequest" }, { "$ref": "#/components/schemas/ClaimBySessionRequest" }] } } } }, "responses": { "200": { "description": "Passport claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" } } } }, "400": { "description": "Invalid request body or passport_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No WorkOSOwnerSession cookie or bearerAgentSession token was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "claim_token_invalid: the claim token is wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimErrorResponse" } } } }, "404": { "description": "no_pending_claim: this passport has no open claim to redeem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimErrorResponse" } } } }, "409": { "description": "passport_already_owned: this passport is already claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimErrorResponse" } } } }, "410": { "description": "passport_superseded: this passport was replaced by a remint while unclaimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimErrorResponse" } } } }, "429": { "description": "Too many claim attempts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/otp-request": { "post": { "x-flint-release-state": "staging", "security": [], "tags": ["Agent Sessions"], "operationId": "requestAgentOtp", "summary": "Request a one-time sign-in code by email", "description": "The agent-native front door: an MCP agent (or the SPA) calls this first with an inbox address, reads the code WorkOS Magic Auth sends to that inbox, then calls POST /api/auth/otp-verify. Rate limited to 5 requests per email and 20 per IP per 10 minutes. Never echoes the code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpRequestRequest" } } } }, "responses": { "200": { "description": "Code sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpRequestResponse" } } } }, "400": { "description": "invalid_email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "otp_rate_limited, with reason \"ip\", \"email\", or \"provider\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "auth_provider_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "auth_not_configured: WORKOS_API_KEY or WORKOS_CLIENT_ID is not set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/otp-verify": { "post": { "x-flint-release-state": "staging", "security": [], "tags": ["Agent Sessions"], "operationId": "verifyAgentOtp", "summary": "Verify a one-time code and mint a session", "description": "Verifies the WorkOS Magic Auth code from POST /api/auth/otp-request and mints both a browser session cookie (so this endpoint also serves the SPA) and a bearer agent session token, so an MCP agent can authenticate without ever holding a cookie. Runs the same new-account onboarding side effects as the browser OAuth callback. Never echoes the code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpVerifyRequest" } } } }, "responses": { "200": { "description": "Signed in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpVerifyResponse" } } } }, "400": { "description": "otp_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "otp_rate_limited, with reason \"ip\" or \"provider\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "auth_provider_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "auth_not_configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/session-revoke": { "post": { "x-flint-release-state": "staging", "security": [{ "bearerAgentSession": [] }], "tags": ["Agent Sessions"], "operationId": "revokeAgentSession", "summary": "Revoke the presented bearer agent session", "description": "Ends a session_token immediately instead of waiting for its TTL. Idempotent: revoking an already-revoked or unknown token still returns ok.", "responses": { "200": { "description": "Revoked (or already revoked/unknown; idempotent).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRevokeResponse" } } } }, "401": { "description": "not_authenticated: no bearer token was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "VerifyRequest": { "type": "object", "required": ["nonce", "timestamp", "transaction"], "properties": { "nonce": { "type": "string", "minLength": 8, "description": "Unique replay-protection nonce. UUID v4 is recommended." }, "timestamp": { "type": "string", "format": "date-time", "description": "Request timestamp. Must be within the server replay-protection window." }, "partner_id": { "type": "string", "default": "sandbox_public", "description": "Merchant or platform identifier used for partner-scoped public IDs." }, "merchant_reference": { "type": "string", "description": "Merchant transaction, invoice, or API access reference." }, "transaction": { "$ref": "#/components/schemas/TransactionIntent" }, "declared_scope": { "$ref": "#/components/schemas/AuthorizationScope" }, "agent_claim": { "$ref": "#/components/schemas/AgentClaim" } } } }, "/api/auth/otp-request": { "post": { "x-flint-release-state": "staging", "security": [], "tags": ["Agent Sessions"], "operationId": "requestAgentOtp", "summary": "Request a one-time sign-in code by email", "description": "The agent-native front door: an MCP agent (or the SPA) calls this first with an inbox address, reads the code WorkOS Magic Auth sends to that inbox, then calls POST /api/auth/otp-verify. Rate limited to 5 requests per email and 20 per IP per 10 minutes. Never echoes the code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpRequestRequest" } } } }, "responses": { "200": { "description": "Code sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpRequestResponse" } } } }, "400": { "description": "invalid_email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "otp_rate_limited, with reason \"ip\", \"email\", or \"provider\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "auth_provider_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "auth_not_configured: WORKOS_API_KEY or WORKOS_CLIENT_ID is not set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/otp-verify": { "post": { "x-flint-release-state": "staging", "security": [], "tags": ["Agent Sessions"], "operationId": "verifyAgentOtp", "summary": "Verify a one-time code and mint a session", "description": "Verifies the WorkOS Magic Auth code from POST /api/auth/otp-request and mints both a browser session cookie (so this endpoint also serves the SPA) and a bearer agent session token, so an MCP agent can authenticate without ever holding a cookie. Runs the same new-account onboarding side effects as the browser OAuth callback. Never echoes the code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpVerifyRequest" } } } }, "responses": { "200": { "description": "Signed in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpVerifyResponse" } } } }, "400": { "description": "otp_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "otp_rate_limited, with reason \"ip\" or \"provider\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "auth_provider_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "auth_not_configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/session-revoke": { "post": { "x-flint-release-state": "staging", "security": [{ "bearerAgentSession": [] }], "tags": ["Agent Sessions"], "operationId": "revokeAgentSession", "summary": "Revoke the presented bearer agent session", "description": "Ends a session_token immediately instead of waiting for its TTL. Idempotent: revoking an already-revoked or unknown token still returns ok.", "responses": { "200": { "description": "Revoked (or already revoked/unknown; idempotent).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRevokeResponse" } } } }, "401": { "description": "not_authenticated: no bearer token was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "VerifyRequest": { "type": "object", "required": ["nonce", "timestamp", "transaction"], "properties": { "nonce": { "type": "string", "minLength": 8, "description": "Unique replay-protection nonce. UUID v4 is recommended." }, "timestamp": { "type": "string", "format": "date-time", "description": "Request timestamp. Must be within the server replay-protection window." }, "partner_id": { "type": "string", "default": "sandbox_public", "description": "Merchant or platform identifier used for partner-scoped public IDs." }, "merchant_reference": { "type": "string", "description": "Merchant transaction, invoice, or API access reference." }, "transaction": { "$ref": "#/components/schemas/TransactionIntent" }, "declared_scope": { "$ref": "#/components/schemas/AuthorizationScope" }, "agent_claim": { "$ref": "#/components/schemas/AgentClaim" } } }, "X402ScanRequest": { "type": "object", "additionalProperties": false, "required": ["nonce", "timestamp", "transaction"], "properties": { "nonce": { "type": "string", "minLength": 8, "maxLength": 128 }, "timestamp": { "type": "string", "format": "date-time" }, "passport_id": { "type": "string", "description": "Optional FLINT Agent Passport. Authority credit requires server verification and a match to the verified x402 payer wallet." }, "merchant_reference": { "type": "string" }, "transaction": { "type": "object", "additionalProperties": false, "required": ["action", "chain", "amount_display", "counterparty_address"], "properties": { "action": { "type": "string", "maxLength": 128 }, "reference": { "type": "string" }, "chain": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_A-Za-z0-9]{1,32}$" }, "token": { "type": "object", "additionalProperties": false, "properties": { "symbol": { "type": "string" }, "issuer": { "type": "string" }, "contract": { "type": "string" } } }, "amount_display": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,18})?$" }, "counterparty_address": { "type": "string" }, "direction": { "type": "string" } } }, "agent_claim": { "$ref": "#/components/schemas/X402ScanAgentClaim" } } }, "X402ScanAgentClaim": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string", "maxLength": 256 }, "agent_runtime_hint": { "type": "string", "maxLength": 256 }, "wallet_type": { "type": "string", "maxLength": 256 } } }, "X402ScanResponse": { "type": "object", "required": ["ok", "verdict", "score", "record_id", "record_url", "signed_record", "scan", "service_payment", "receipt_url", "receipt_page_url", "caller_obligation", "passport_binding"], "properties": { "caller_obligation": { "$ref": "#/components/schemas/CallerObligation" }, "step_up": { "type": "object", "description": "Present only when verdict is step_up; the remediation menu." }, "passport_binding": { "$ref": "#/components/schemas/PassportBinding" }, "ok": { "const": true }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "top_reasons": { "type": "array", "items": { "type": "string" } }, "record_id": { "type": "string", "pattern": "^frv_" }, "record_url": { "type": ["string", "null"], "format": "uri", "description": "Human-readable authorization record URL, derived by FLINT from the record ID." }, "receipt_url": { "type": ["string", "null"], "format": "uri", "description": "Machine retrieval URL for the signed settlement-receipt envelope." }, "receipt_page_url": { "type": ["string", "null"], "format": "uri", "description": "Human-readable Scout service-payment receipt URL." }, "signed_record": { "type": "string" }, "record": { "type": "object" }, "scan": { "type": "object", "required": [ "profile", "status", "transaction_intent_commitment", "payer_wallet_commitment", "external_provider_calls", "model_calls", "bounded_paid_path_executed", "external_provider_path_executed", "record_persisted", "record_persistence_status", "replay_protection_status", "trust_graph_ingest_attempted", "passport_upgraded" ], "properties": { "profile": { "const": "marketplace_basic_v1" }, "status": { "const": "completed" }, "transaction_intent_commitment": { "type": "string", "pattern": "^sha256_[a-f0-9]{64}$" }, "payer_wallet_commitment": { "type": "string", "pattern": "^sha256_[a-f0-9]{64}$" }, "external_provider_calls": { "const": 0 }, "model_calls": { "const": 0 }, "bounded_paid_path_executed": { "const": true }, "external_provider_path_executed": { "const": false }, "record_persisted": { "type": "boolean" }, "record_persistence_status": { "enum": ["persisted", "unavailable"] }, "replay_protection_status": { "enum": ["completed", "unavailable"] }, "trust_graph_ingest_attempted": { "type": "boolean" }, "passport_upgraded": { "type": "boolean" } } }, "service_payment": { "type": "object", "required": ["purpose", "status", "distinct_from_scanned_transaction", "receipt_status", "receipt_id"], "properties": { "purpose": { "const": "flint_transaction_scan_service_fee" }, "status": { "const": "settled" }, "method": { "type": "string", "enum": ["x402", "scout_credit"], "description": "How this scan's service fee was paid. scout_credit means no x402 settlement or fsr_ receipt was issued for this call." }, "distinct_from_scanned_transaction": { "const": true }, "receipt_status": { "enum": ["issued", "unavailable", "disabled"] }, "receipt_id": { "type": ["string", "null"] }, "credits_remaining": { "type": ["integer", "null"], "description": "Present when method is scout_credit." } } }, "settlement_receipt": { "type": ["object", "null"] }, "compliance": { "type": "object" } } }, "X402VerifyRequest": { "allOf": [ { "$ref": "#/components/schemas/VerifyRequest" }, { "type": "object", "required": ["agent_claim"], "properties": { "passport_id": { "type": "string", "pattern": "^kya_", "description": "Optional verified Agent Passport used by the owner-issued preflight capability." }, "agent_claim": { "$ref": "#/components/schemas/AgentClaim" } } } ] }, "X402VerifyResponse": { "type": "object", "required": [ "ok", "verdict", "score", "record_id", "record_url", "signed_record", "record", "receipt_status", "settlement_receipt", "receipt_url", "receipt_page_url" ], "properties": { "ok": { "const": true }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "top_reasons": { "type": "array", "items": { "type": "string" } }, "record_id": { "type": "string", "pattern": "^frv_" }, "record_url": { "type": ["string", "null"], "format": "uri", "description": "Human-readable authorization record URL, derived by FLINT from the record ID." }, "receipt_url": { "type": ["string", "null"], "format": "uri", "description": "Machine retrieval URL for the signed settlement-receipt envelope." }, "receipt_page_url": { "type": ["string", "null"], "format": "uri", "description": "Human-readable Scout service-payment receipt URL." }, "signed_record": { "type": "string", "description": "ES256 compact JWS for the authorization record." }, "record": { "$ref": "#/components/schemas/HybridEnvelope" }, "step_up": { "type": "object" }, "compliance": { "type": "object" }, "receipt_status": { "type": "string", "enum": ["issued", "unavailable", "disabled", "not_issued"] }, "settlement_receipt": { "oneOf": [ { "type": "object", "required": ["receipt_id", "record", "idempotent"], "properties": { "receipt_id": { "type": "string", "pattern": "^fsr_" }, "record": { "$ref": "#/components/schemas/HybridEnvelope" }, "idempotent": { "type": "boolean" } } }, { "type": "null" } ] } } }, "HybridEnvelope": { "type": "object", "required": ["jws"], "properties": { "envelope_version": { "type": ["string", "null"], "example": "hybrid-v0" }, "jws": { "type": "string", "description": "ES256 compact JWS." }, "pq_signature": { "type": ["string", "null"], "description": "Parallel ML-DSA-65 signature when configured." }, "pq_kid": { "type": ["string", "null"] }, "pq_alg": { "type": ["string", "null"] } } }, "RecordAcknowledgment": { "type": "object", "required": ["received_at", "acknowledger", "signature_status", "method"], "properties": { "received_at": { "type": "string", "format": "date-time" }, "acknowledger": { "type": "object", "required": ["agent_id", "passport_id", "wallet_address"], "properties": { "agent_id": { "type": "string", "maxLength": 256 }, "passport_id": { "type": ["string", "null"], "maxLength": 256 }, "wallet_address": { "type": ["string", "null"], "maxLength": 256 } } }, "signature_status": { "type": "string", "enum": ["verified", "unverified_claim"] }, "method": { "type": "string", "enum": ["none", "es256_jws", "eip191_wallet", "unsupported"] } } }, "HybridEnvelopeWithAcknowledgments": { "allOf": [ { "$ref": "#/components/schemas/HybridEnvelope" }, { "type": "object", "required": ["acknowledgments"], "properties": { "acknowledgments": { "type": "array", "items": { "$ref": "#/components/schemas/RecordAcknowledgment" } } } } ] }, "DecodedRecordResponse": { "type": "object", "required": ["header", "envelope_version", "pq_signature", "record", "acknowledgments", "settlement_receipt"], "properties": { "header": { "type": "object" }, "envelope_version": { "type": ["string", "null"] }, "pq_signature": { "type": "object", "required": ["present"], "properties": { "present": { "type": "boolean" }, "alg": { "type": ["string", "null"] }, "kid": { "type": ["string", "null"] } } }, "record": { "type": "object", "description": "Decoded record payload. This view is not itself signed." }, "acknowledgments": { "type": "array", "items": { "$ref": "#/components/schemas/RecordAcknowledgment" } }, "settlement_receipt": { "oneOf": [ { "type": "object", "required": ["receipt_id", "href"], "properties": { "receipt_id": { "type": "string", "pattern": "^fsr_" }, "href": { "type": "string" } } }, { "type": "null" } ] } } }, "RecordAcknowledgmentRequest": { "type": "object", "additionalProperties": false, "required": ["acknowledger", "payload_hash"], "properties": { "acknowledger": { "type": "object", "additionalProperties": false, "required": ["agent_id"], "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "passport_id": { "type": "string", "maxLength": 256 }, "wallet_address": { "type": "string", "maxLength": 256 } } }, "payload_hash": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "signature": { "type": "object", "required": ["alg", "value"], "properties": { "alg": { "type": "string", "description": "ES256 or EIP-191 are verifiable; other values are retained as unsupported claims." }, "value": { "type": "string", "maxLength": 8192 }, "jwk": { "type": "object", "description": "Only a public JWK can produce verified status. A JWK containing private members is retained as an unverified claim." } } } } }, "RecordAcknowledgmentResponse": { "type": "object", "required": ["ok", "record_id", "signature_status", "received_at", "acknowledgment"], "properties": { "ok": { "const": true }, "record_id": { "type": "string", "pattern": "^frv_" }, "signature_status": { "type": "string", "enum": ["verified", "unverified_claim"] }, "received_at": { "type": "string", "format": "date-time" }, "acknowledgment": { "$ref": "#/components/schemas/RecordAcknowledgment" } } }, "DecodedSettlementReceiptResponse": { "type": "object", "required": ["header", "envelope_version", "pq_signature", "settlement_receipt"], "properties": { "header": { "type": "object" }, "envelope_version": { "type": ["string", "null"] }, "pq_signature": { "type": "object", "required": ["present"], "properties": { "present": { "type": "boolean" }, "alg": { "type": ["string", "null"] }, "kid": { "type": ["string", "null"] } } }, "settlement_receipt": { "type": "object", "description": "Decoded receipt payload. This view is not itself signed." } } }, "CircleReadiness": { "type": "object", "required": ["provider", "status", "configured", "integration_ready", "operationally_verified", "provider_call_performed"], "properties": { "provider": { "const": "circle_compliance_engine" }, "status": { "type": "string", "enum": ["configured_unverified", "unavailable"] }, "configured": { "type": "boolean" }, "integration_ready": { "const": false }, "operationally_verified": { "const": false }, "provider_call_performed": { "const": false } } }, "SettlementReceiptReadiness": { "type": "object", "required": [ "network", "production", "activation_enabled", "activation_mode", "signing_configuration_state", "signing_configuration_valid", "signing_configuration_error", "public_base_url_configured", "public_base_url_valid", "production_canonical_origin", "preflight_ready", "operationally_verified", "operational_verification" ], "properties": { "network": { "type": "string" }, "production": { "type": "boolean" }, "activation_enabled": { "type": "boolean" }, "activation_mode": { "type": "string", "enum": ["testnet_default", "explicit_opt_in", "disabled"] }, "signing_configuration_state": { "type": "string", "enum": ["absent", "incomplete", "complete"] }, "signing_configuration_valid": { "type": "boolean" }, "signing_configuration_error": { "type": ["string", "null"] }, "public_base_url_configured": { "type": "boolean" }, "public_base_url_valid": { "type": "boolean" }, "production_canonical_origin": { "type": "boolean" }, "preflight_ready": { "type": "boolean" }, "operationally_verified": { "type": "boolean" }, "operational_verification": { "type": "object", "required": ["status", "evidence_type", "network", "transaction_hash"], "properties": { "status": { "type": "string", "enum": ["funded_settlement_verified", "invalid_transaction_evidence", "not_verified"] }, "evidence_type": { "type": ["string", "null"], "enum": ["base_transaction", null] }, "network": { "type": ["string", "null"] }, "transaction_hash": { "type": ["string", "null"], "pattern": "^0x[0-9a-fA-F]{64}$" } } } } }, "X402ReadinessResponse": { "type": "object", "required": ["ok", "route", "circle", "settlement_receipt", "marketplace_scan", "detail"], "properties": { "ok": { "const": true }, "route": { "const": "x402_verify" }, "circle": { "$ref": "#/components/schemas/CircleReadiness" }, "settlement_receipt": { "$ref": "#/components/schemas/SettlementReceiptReadiness" }, "marketplace_scan": { "type": "object", "required": ["route", "settlement_receipt"], "properties": { "route": { "const": "/api/x402/scan" }, "settlement_receipt": { "$ref": "#/components/schemas/SettlementReceiptReadiness" } } }, "detail": { "type": "string" } } }, "X401ProofResult": { "type": "object", "required": ["scheme", "version", "request_id"], "properties": { "scheme": { "const": "x401" }, "version": { "const": "0.2.0" }, "request_id": { "const": "flint-principal-identity-v1" }, "result": { "type": "string" }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number" }, "record_id": { "type": "string", "pattern": "^frv_" }, "error": { "type": "string" }, "error_description": { "type": "string" } } }, "X401ChallengeResponse": { "type": "object", "required": ["error", "scheme", "version", "proof_request"], "properties": { "error": { "const": "proof_required" }, "scheme": { "const": "x401" }, "version": { "const": "0.2.0" }, "proof_request": { "type": "object" } } }, "X401VerifyResponse": { "type": "object", "required": ["ok", "protocol", "route", "verdict", "score", "record_id", "signed_record", "record", "x401"], "properties": { "ok": { "const": true }, "protocol": { "const": "x401" }, "route": { "const": "/api/x401/verify" }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "top_reasons": { "type": "array", "items": { "type": "string" } }, "record_id": { "type": "string", "pattern": "^frv_" }, "signed_record": { "type": "string" }, "record": { "$ref": "#/components/schemas/HybridEnvelope" }, "x401": { "type": "object", "required": ["request_id", "principal_attestation_source", "principal"], "properties": { "request_id": { "const": "flint-principal-identity-v1" }, "principal_attestation_source": { "const": "x401" }, "principal": { "type": "object" } } } } }, "TransactionIntent": { "type": "object", "required": ["amount_display"], "properties": { "amount_display": { "type": "string", "description": "Human-readable transaction amount." }, "amount_atomic": { "type": ["string", "null"], "description": "Atomic token amount when available." }, "asset": { "type": "string", "description": "Asset symbol, such as USDC." }, "chain": { "type": "string", "description": "CAIP-2 chain identifier." }, "counterparty_address": { "type": ["string", "null"], "description": "Wallet or counterparty address." }, "merchant_reference": { "type": ["string", "null"], "description": "Merchant reference for the intended action." }, "tx_intent_hash": { "type": ["string", "null"], "description": "Optional hash of the transaction intent." } } }, "AuthorizationScope": { "type": "object", "properties": { "max_amount_per_tx_display": { "type": "string", "description": "Maximum amount authorized per transaction." }, "allowed_counterparties": { "type": "array", "items": { "type": "string" }, "description": "Allowed merchant references or counterparties." }, "time_window_end": { "type": "string", "format": "date-time", "description": "Expiration time for the declared scope." } } }, "AgentClaim": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Agent-provided stable identifier or handle." }, "principal_hint": { "type": "string", "description": "Principal or authority hint supplied by the agent." }, "agent_runtime_hint": { "type": "string", "description": "Agent runtime category, such as browser, api_client, or api_meter." }, "wallet_type": { "type": "string", "description": "Wallet or account type claimed by the agent." } } }, "VerdictDecision": { "type": "string", "enum": ["allow", "step_up", "review", "block"] }, "OutcomeRequest": { "type": "object", "required": ["record_id", "outcome"], "properties": { "record_id": { "type": "string", "pattern": "^frv_", "description": "Signed verification record ID." }, "outcome": { "type": "string", "enum": ["completed", "disputed", "flagged"] }, "merchant_note": { "type": ["string", "null"] }, "partner_id": { "type": "string", "default": "sandbox_public" } } }, "OutcomeResponse": { "type": "object", "required": ["ok", "outcome_id", "record_id", "outcome", "stored_at"], "properties": { "ok": { "type": "boolean" }, "outcome_id": { "type": "string" }, "record_id": { "type": "string" }, "outcome": { "type": "string", "enum": ["completed", "disputed", "flagged"] }, "stored_at": { "type": "string", "format": "date-time" } } }, "AgentReputationResponse": { "type": "object", "required": ["ok", "agent_reputation"], "properties": { "ok": { "type": "boolean" }, "agent_reputation": { "$ref": "#/components/schemas/AgentReputation" } } }, "AgentReputation": { "type": "object", "required": ["flint_agent_id", "global_stats", "runtime_diversity", "principal_consistency", "recent_outcomes"], "properties": { "flint_agent_id": { "type": "string" }, "global_stats": { "type": "object", "required": ["first_seen", "total_transactions", "dispute_rate"], "properties": { "first_seen": { "type": ["string", "null"], "format": "date-time" }, "total_transactions": { "type": "integer", "minimum": 0 }, "dispute_rate": { "type": "number", "minimum": 0 } } }, "runtime_diversity": { "type": "integer", "minimum": 0 }, "principal_consistency": { "type": "integer", "minimum": 0 }, "recent_outcomes": { "type": "array", "items": { "type": "string", "enum": ["completed", "disputed", "flagged"] } } } }, "GraphHealthResponse": { "type": "object", "required": ["ok", "status"], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": ["ok", "configured", "unconfigured"] }, "latency_ms": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } }, "TrustManifest": { "type": "object", "required": ["version", "requires_flint_authorization", "partner_id"], "properties": { "version": { "type": "string" }, "issuer": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "requires_flint_authorization": { "type": "boolean" }, "partner_id": { "type": "string" }, "authorization_record": { "type": "object" }, "agent_commerce": { "type": "object" }, "trust_graph": { "type": "object" }, "outcome_feedback": { "type": "object" }, "docs": { "type": "object" }, "privacy": { "type": "object" }, "contact": { "type": "object" } } }, "ErrorResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" }, "detail": { "type": "string" }, "pay_recipe": { "$ref": "#/components/schemas/PayRecipe" } } }, "PayRecipe": { "type": "object", "description": "Present on a 402 payment-required body. Four ways to satisfy this challenge.", "required": ["awal", "script", "credits", "browser"], "properties": { "awal": { "type": "string", "description": "One-line awal CLI command that pays and retries." }, "script": { "type": "string", "description": "scripts/scout-pay.mjs invocation using SCOUT_PAYER_PRIVATE_KEY." }, "credits": { "type": "string", "description": "Prepaid credits path: buy once via scout_credits_topup, then pass session_token to run_flint_scout." }, "browser": { "type": "string", "format": "uri", "description": "Human browser flow at /verify#call-scout." } } }, "CallerObligation": { "type": "object", "description": "FLINT does not hold keys and cannot stop the scanned transfer. This is the enforce-or-attest contract: the caller (or passport owner) must report what happened.", "required": ["enforcement", "statement", "report_url", "caller_binding_token"], "properties": { "enforcement": { "const": "caller" }, "statement": { "type": "string" }, "report_url": { "type": "string", "format": "uri" }, "caller_binding_token": { "type": "string", "description": "Lets an anonymous x402 caller report its own outcome without an account. Random, single-use per record." } } }, "PassportBinding": { "type": "object", "description": "Whether a passport_id was presented on this scan and whether it was creditable. A presented passport's flint_agent_id is always carried here, even when not credited; the record's own Trust Graph merge key (agent.flint_agent_id / graph.flint_agent_id) is the passport's faid only when credited is true.", "required": ["presented"], "properties": { "presented": { "type": "boolean" }, "passport_id": { "type": ["string", "null"] }, "flint_agent_id": { "type": ["string", "null"] }, "credited": { "type": "boolean" }, "binding": { "type": ["string", "null"], "enum": ["credited", "presented_uncredited", null], "description": "How this record's identity relates to the presented passport. null when no passport reached identity verification at all." }, "reason_codes": { "type": "array", "items": { "type": "string" } } } }, "RecordOutcome": { "type": "object", "description": "What actually happened after a scan, as reported through POST /api/records/{record_id}/outcome. GET /api/records/{id} and GET /api/counterparty/{address} strip reporter.ref from this shape before returning it publicly; reporter.type is always kept.", "required": ["outcome", "reported_at", "reporter", "override"], "properties": { "outcome": { "type": "string", "enum": ["executed", "held", "executed_despite_block", "cancelled"] }, "tx_hash": { "type": ["string", "null"] }, "chain": { "type": ["string", "null"] }, "reported_at": { "type": "string", "format": "date-time" }, "reporter": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["owner_session", "caller", "partner"] }, "ref": { "type": ["string", "null"], "description": "Stripped from every public projection of this shape; present only in the reporter's own POST response." } } }, "verdict_at_scan": { "type": ["string", "null"] }, "override": { "type": "boolean", "description": "True when verdict_at_scan was block and outcome starts with executed." }, "tx_verified": { "type": ["boolean", "null"], "description": "Best-effort etherscan check of tx_hash against the scanned counterparty and amount. null when Etherscan is not configured or the check was inconclusive; a definitive non-match is rejected 400 tx_hash_mismatch instead of being stored." }, "ledger_recorded": { "type": "boolean", "description": "True only when an override was actually written to the passport's Scout ledger and Sentinel was notified: requires the override to be reported while the record's passport binding was credited, or by the passport owner's own session." }, "reason": { "type": ["string", "null"], "enum": ["passport_not_credited", null], "description": "Set to passport_not_credited when an override could not be written to the passport's Scout ledger because the binding was not credited and the reporter was not the owner's session." } } }, "OutcomeReportRequest": { "type": "object", "additionalProperties": false, "required": ["outcome"], "properties": { "outcome": { "type": "string", "enum": ["executed", "held", "executed_despite_block", "cancelled"] }, "tx_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Required when outcome starts with executed." }, "chain": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_A-Za-z0-9]{1,32}$" }, "note": { "type": "string", "maxLength": 280 }, "caller_binding_token": { "type": "string", "description": "Required to report anonymously as the caller instead of via session or partner credential." } } }, "OutcomeReportResponse": { "type": "object", "required": ["ok", "record_id", "outcome"], "properties": { "ok": { "type": "boolean" }, "record_id": { "type": "string", "pattern": "^frv_" }, "outcome": { "$ref": "#/components/schemas/RecordOutcome" } } }, "CounterpartyScan": { "type": "object", "required": ["record_id", "record_url", "issued_at", "verdict", "amount_display", "token", "flint_agent_id", "passport_id", "passport_url", "outcome"], "properties": { "record_id": { "type": ["string", "null"] }, "record_url": { "type": ["string", "null"], "format": "uri" }, "issued_at": { "type": ["string", "null"], "format": "date-time" }, "verdict": { "type": ["string", "null"] }, "amount_display": { "type": ["string", "null"] }, "token": { "type": ["string", "null"] }, "flint_agent_id": { "type": ["string", "null"] }, "passport_id": { "type": ["string", "null"] }, "passport_url": { "type": ["string", "null"], "format": "uri" }, "outcome": { "oneOf": [{ "$ref": "#/components/schemas/RecordOutcome" }, { "type": "null" }] } } }, "CounterpartyResponse": { "type": "object", "required": ["ok", "address", "chain", "scans", "count"], "properties": { "ok": { "const": true }, "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" }, "chain": { "type": "string" }, "scans": { "type": "array", "items": { "$ref": "#/components/schemas/CounterpartyScan" } }, "count": { "type": "integer", "minimum": 0 } } }, "ScoutCreditLedgerEntry": { "type": "object", "required": ["at", "kind", "amount"], "properties": { "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": ["topup", "debit", "refund"] }, "amount": { "type": "integer" }, "receipt_id": { "type": ["string", "null"] }, "record_id": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] } } }, "ScoutCreditsTopupResponse": { "type": "object", "required": ["ok", "credits_added", "balance", "receipt_id", "receipt_url"], "properties": { "ok": { "const": true }, "credits_added": { "const": 100 }, "balance": { "type": "integer", "minimum": 0 }, "receipt_id": { "type": "string", "pattern": "^fsr_" }, "receipt_url": { "type": ["string", "null"], "format": "uri" } } }, "ScoutCreditsBalanceResponse": { "type": "object", "required": ["ok", "balance", "purchased_total", "used_total", "ledger"], "properties": { "ok": { "type": "boolean" }, "balance": { "type": "integer", "minimum": 0 }, "purchased_total": { "type": "integer", "minimum": 0 }, "used_total": { "type": "integer", "minimum": 0 }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/ScoutCreditLedgerEntry" } } } }, "ScoutCreditsTopupIntentResponse": { "type": "object", "required": ["ok", "topup_id", "pay_url", "expires_at", "credits", "price_usd"], "properties": { "ok": { "const": true }, "topup_id": { "type": "string", "pattern": "^sct_" }, "pay_url": { "type": "string", "format": "uri", "description": "POST /api/x402/scout-credits/{topup_id}. No session needed to pay it." }, "expires_at": { "type": "string", "format": "date-time" }, "credits": { "const": 100 }, "price_usd": { "const": 1 } } }, "ScoutCreditsTopupIntentSettledResponse": { "type": "object", "required": ["ok", "topup_id", "credits_added", "balance", "receipt_id", "receipt_url"], "properties": { "ok": { "const": true }, "topup_id": { "type": "string", "pattern": "^sct_" }, "credits_added": { "const": 100 }, "balance": { "type": "integer", "minimum": 0 }, "receipt_id": { "type": "string", "pattern": "^fsr_" }, "receipt_url": { "type": ["string", "null"], "format": "uri" } } }, "ErrorResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" }, "detail": { "type": "string" } } }, "PassportIssueRequest": { "type": "object", "required": ["agent"], "properties": { "agent": { "type": "object", "description": "Agent identity. Signed into the passport.", "properties": { "agent_id": { "type": "string" }, "agent_name": { "type": "string" }, "controller_id": { "type": "string" }, "controller_type": { "type": "string", "enum": ["user", "organization"] }, "wallet_address": { "type": "string" }, "attestations": { "type": "array", "items": { "type": "object" } }, "controller_name": { "type": "string", "maxLength": 120, "description": "Optional human-readable display label for the controller, signed into the passport identity right after controller_type. Distinct from controller_id: controller_id is the accountable identifier, controller_name is a display label. Null when not supplied." } } }, "mandate": { "type": "object", "description": "Mutable spend authority captured at issue. NOT part of the passport signature.", "properties": { "allowed_actions": { "type": "array", "items": { "type": "string", "enum": [ "commerce_purchase", "checkout.purchase", "invoice.pay", "subscription.renew", "refund.request", "quote.retrieve", "x402_verification_purchase", "stablecoin_transfer", "paid_api_access", "x402_request", "agent_checkout", "delegated_spending", "project.read", "ALL" ], "description": "One FLINT mandate vocabulary action (see api/lib/mandate-actions.js), or the \"ALL\" preset. \"ALL\" (case-insensitive) or the legacy alias \"all_commerce_v1\" expands server-side to the full vocabulary list at mint or update time; the stored mandate keeps the expanded allowed_actions and also records preset: \"ALL\" so a client can render one checkbox instead of the full list. A string outside this vocabulary is kept for backward compatibility but is reported back in mandate_warnings and will not match any scan until it is added to the vocabulary or aliased." } }, "max_transaction_amount": { "type": "number" }, "notes": { "type": "string" } } }, "supersede_management_token": { "type": "string", "description": "Optional. The management_token (raw claim token) of a specific prior UNCLAIMED passport with the same agent_id and controller_id. Presenting it authorizes superseding that prior passport at mint even with no authenticated session, since it proves possession of that prior's own claim link. Without it, and without a session whose controller_assurance is verified or command, a remint that reuses a prior's agent_id and controller_id does not supersede that prior; the prior is left alone and reported back in related_passports with a warning instead." } } }, "Mandate": { "type": "object", "description": "Unsigned, mutable mandate config read at decision time.", "properties": { "passport_id": { "type": "string" }, "allowed_actions": { "type": "array", "items": { "type": "string", "description": "A FLINT mandate vocabulary action. When the mandate was set with the ALL preset this is the full expanded vocabulary list, not the literal string \"ALL\"." } }, "max_transaction_amount": { "type": "number" }, "notes": { "type": ["string", "null"] }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "preset": { "type": ["string", "null"], "enum": ["ALL", null], "description": "\"ALL\" when allowed_actions was set via the ALL preset (or its legacy alias all_commerce_v1) and was expanded server-side to the full vocabulary. Null when allowed_actions was set explicitly." }, "mandate_warnings": { "type": "array", "items": { "type": "string" }, "description": "One warning per allowed_actions entry that is not in the FLINT mandate vocabulary and is not the ALL preset. The action is kept (backward compatible) but will not match actionPermitted until it is added to the vocabulary or aliased." } } }, "PassportResponse": { "type": "object", "properties": { "passport_id": { "type": "string", "description": "kya_ prefix + ULID." }, "flint_agent_id": { "type": "string", "description": "Trust Graph node key (faid_ prefix)." }, "passport": { "type": "object", "description": "Hybrid-v0 signature envelope.", "properties": { "envelope_version": { "type": "string", "example": "hybrid-v0" }, "jws": { "type": "string", "description": "ES256 compact JWS over the identity-only payload." }, "pq_signature": { "type": ["string", "null"], "description": "ML-DSA-65 signature (base64url)." }, "pq_kid": { "type": ["string", "null"] }, "pq_alg": { "type": ["string", "null"] } } }, "mandate": { "$ref": "#/components/schemas/Mandate" }, "verification": { "type": "object", "properties": { "signature_valid": { "type": "boolean" }, "status": { "type": "string" }, "not_expired": { "type": "boolean" }, "valid": { "type": "boolean" } } }, "identity": { "$ref": "#/components/schemas/PassportIdentity" }, "mint_src": { "type": "string", "description": "Sanitized mint source label." }, "owned": { "type": "boolean", "description": "Top-level mirror of ownership.owned, for cheap assertions." }, "unclaimed": { "type": "boolean", "description": "Top-level mirror of ownership.unclaimed." }, "claim_state": { "type": "string", "enum": ["claimed", "pending", "superseded", "none"], "description": "Top-level mirror of ownership.claim_state." }, "superseded_by": { "type": ["string", "null"], "description": "Top-level mirror of ownership.superseded_by." }, "ownership": { "$ref": "#/components/schemas/Ownership" }, "claim_url": { "type": "string", "description": "One-time claim link. Present only on an anonymous (unowned) mint whose claim token was stored successfully. Absent on an owned mint." }, "existing_claimed_passports": { "type": "array", "items": { "type": "string" }, "description": "passport_id values for prior CLAIMED passports with the same controller_id and agent_id that a remint left alone (never superseded automatically). Present only when at least one exists." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Response-level warnings, such as an existing_claimed_passports notice." }, "mandate_warnings": { "type": "array", "items": { "type": "string" }, "description": "Copy of mandate.mandate_warnings, surfaced at the top level for convenience." } } }, "MandateUpdateRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": ["update_mandate"] }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "max_transaction_amount": { "type": "number" }, "notes": { "type": "string" }, "management_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$", "description": "Required to update the mandate of an UNCLAIMED passport: the raw claim token, presented as a management capability. Not needed once the passport is claimed; the owner's session (WorkOSOwnerSession cookie or bearerAgentSession) is used instead." } } }, "MandateUpdateResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "passport_id": { "type": "string" }, "mandate": { "$ref": "#/components/schemas/Mandate" }, "passport_signature_unchanged": { "type": "boolean", "description": "Always true: a mandate update never re-signs the passport." } } }, "PurchaseAuthorizationRequest": { "type": "object", "required": ["action", "shop", "currency", "max_amount"], "properties": { "action": { "type": "string", "enum": ["issue_purchase_authorization"] }, "shop": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "max_amount": { "type": "number", "exclusiveMinimum": 0 } } }, "PurchaseAuthorizationEnvelope": { "type": "object", "required": ["envelope_version", "jws"], "properties": { "envelope_version": { "type": "string", "example": "hybrid-v0" }, "jws": { "type": "string", "description": "ES256 compact JWS over the purchase authorization." }, "pq_signature": { "type": ["string", "null"], "description": "Parallel ML-DSA-65 signature when configured." }, "pq_kid": { "type": ["string", "null"] }, "pq_alg": { "type": ["string", "null"] } } }, "PurchaseAuthorizationResponse": { "type": "object", "required": ["ok", "authorization", "purchase_authorization"], "properties": { "ok": { "type": "boolean" }, "authorization": { "type": "object", "description": "Decoded owner authorization claims, including Passport, shop, action, amount, currency, mandate version, and expiry." }, "purchase_authorization": { "$ref": "#/components/schemas/PurchaseAuthorizationEnvelope" }, "usage": { "type": "string" } } }, "Ownership": { "type": "object", "description": "Public-safe ownership and claim lifecycle state for a passport. Never includes emails or raw WorkOS user ids. Identical shape on the issue response, GET /api/passport/{passport_id}, and POST /api/account/claim.", "properties": { "owned": { "type": "boolean", "description": "True once a FLINT account holds this passport." }, "unclaimed": { "type": "boolean", "description": "The logical negation of owned." }, "claimed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the passport was claimed. Null while unclaimed." }, "owner_account_ref": { "type": ["string", "null"], "description": "One-way account reference: \"acct_\" followed by the first 16 hex characters of sha256(owner user id). Never the raw WorkOS user id or email. Null while unclaimed." }, "claim_state": { "type": "string", "enum": ["claimed", "pending", "superseded", "none"], "description": "\"claimed\": owned. \"pending\": unclaimed with an open claim token. \"superseded\": unclaimed and replaced by a remint. \"none\": unclaimed with no open claim (claim-token storage failed at mint, or it was consumed with no refresh)." }, "superseded_by": { "type": ["string", "null"], "description": "passport_id of the passport that superseded this one, when this passport was UNCLAIMED at the time of a remint with the same controller_id and agent_id. Null otherwise. A CLAIMED passport is never superseded automatically." }, "supersedes": { "type": "array", "items": { "type": "string" }, "description": "passport_id values this passport superseded at mint (prior unclaimed passports for the same controller_id and agent_id)." }, "protection_state": { "type": "string", "enum": ["unprotected", "armed_no_channel", "protected", "frozen", "revoked"], "description": "Sentinel protection summary: unprotected (not claimed or not armed), armed_no_channel (armed, no alert channel linked), protected (armed with a channel), frozen, or revoked." } } }, "PassportIdentity": { "type": "object", "description": "The identity-only payload that is hybrid-signed into the passport envelope. record_version stays \"1.0\": controller_name and controller_assurance are additive fields, not a version bump.", "properties": { "passport_id": { "type": "string" }, "record_type": { "type": "string", "example": "agent_passport" }, "record_version": { "type": "string", "example": "1.0" }, "issuer": { "type": "string", "example": "flint" }, "issuer_key_id": { "type": "string" }, "status": { "type": "string", "example": "stamped" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "agent_id": { "type": "string" }, "agent_name": { "type": ["string", "null"] }, "controller_id": { "type": "string", "description": "Who is accountable on the signed identity. Not the same as the FLINT account that owns the passport (see Ownership.owner_account_ref)." }, "controller_type": { "type": "string", "enum": ["user", "organization"] }, "controller_name": { "type": ["string", "null"], "maxLength": 120, "description": "Optional human-readable display label for the controller. Null when not supplied." }, "controller_assurance": { "type": "string", "enum": ["verified", "unverified", "command"], "description": "\"command\" when FLINT Command set the controller. \"verified\" when the minting session's account email equals controller_id (case-insensitive), or an authenticated session's org is the controller. \"unverified\" otherwise, including every anonymous mint." }, "wallet_address": { "type": "string" }, "attestations": { "type": "array", "items": { "type": "object" } }, "core_record_hash": { "type": "string" } } }, "BeginClaimRequest": { "type": "object", "required": ["action", "claim_token"], "properties": { "action": { "type": "string", "enum": ["begin_claim"] }, "claim_token": { "type": "string", "description": "The one-time claim token from the mint's claim_url." } } }, "BeginClaimResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "claim_state": { "type": "string", "enum": ["pending"] }, "passport_id": { "type": "string" } } }, "RefreshClaimTokenRequest": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["refresh_claim_token"] }, "management_token": { "type": "string", "description": "The current raw claim token, even one about to be superseded. Optional when the caller's session (WorkOSOwnerSession cookie or bearerAgentSession) already began this passport's claim, or minted it." } } }, "RefreshClaimTokenResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "passport_id": { "type": "string" }, "claim_url": { "type": "string", "description": "New one-time claim link. The old link stops working." }, "claim_token": { "type": "string", "description": "New raw claim token, equal to management_token." }, "management_token": { "type": "string" }, "claim_state": { "type": "string", "enum": ["pending"] }, "refreshed_at": { "type": "string", "format": "date-time" } } }, "ClaimErrorResponse": { "type": "object", "description": "Every non-owned claim failure returns a distinct reason so a caller (UI or MCP agent) can tell them apart, instead of one shared error string.", "properties": { "error": { "type": "string", "enum": ["passport_already_owned", "passport_superseded", "claim_token_invalid", "no_pending_claim"] }, "reason": { "type": "string", "enum": ["owned", "superseded", "invalid_token", "no_pending_claim"] }, "superseded_by": { "type": "string", "description": "Present only when error is passport_superseded." }, "message": { "type": "string", "description": "Human-readable copy for the UI." } } }, "ClaimByTokenRequest": { "type": "object", "required": ["passport_id", "claim_token"], "properties": { "passport_id": { "type": "string", "pattern": "^kya_" }, "claim_token": { "type": "string", "description": "The one-time claim token from the mint's claim_url." } } }, "ClaimBySessionRequest": { "type": "object", "required": ["passport_id"], "properties": { "passport_id": { "type": "string", "pattern": "^kya_" } }, "description": "Valid only when the caller's authenticated account already holds a pending-claim binding for this passport_id: begin_claim while signed in, refresh_claim_token while signed in, the MCP claim flow, or the flint_claim_intent cookie set by begin_claim while signed out (survives an OTP delay and the /welcome new-account redirect within its 30-minute window)." }, "ClaimResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "owned": { "type": "boolean", "enum": [true] }, "passport_id": { "type": "string" }, "passport_url": { "type": "string" }, "ownership": { "$ref": "#/components/schemas/Ownership" } } }, "OtpRequestRequest": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } }, "OtpRequestResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "delivery": { "type": "string", "enum": ["email"] }, "expires_in_seconds": { "type": "integer" } } }, "OtpVerifyRequest": { "type": "object", "required": ["email", "code"], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "description": "The one-time code delivered to the inbox by /api/auth/otp-request." }, "label": { "type": "string", "maxLength": 120, "description": "Optional human-readable label for the resulting session, such as the agent or workflow name." } } }, "OtpVerifyResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "session_token": { "type": "string", "description": "Bearer agent session token (\"flint_sess_\" prefix). Pass it as Authorization: Bearer on later calls. Treat it like a password; never log it." }, "expires_at": { "type": "string", "format": "date-time" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_verified": { "type": "boolean" } } } } }, "SessionRevokeResponse": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "securitySchemes": { "WorkOSOwnerSession": { "type": "apiKey", "in": "cookie", "name": "flint_session", "description": "Sealed WorkOS session required for claimed-Passport owner actions. Unclaimed mandate updates require the claim token as a management capability." }, "PartnerServiceBearer": { "type": "http", "scheme": "bearer", "description": "Server-only partner credential. The authenticated partner must match the partner in the stored signed verification record." }, "X402Payment": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "Canonical x402 v2 payment proof on a paid retry. Initial unpaid challenge requests require no payment proof." }, "FlintCapability": { "type": "apiKey", "in": "header", "name": "FLINT-CAPABILITY", "description": "Short-lived Passport-owner-issued capability bound to the exact x402 Verify request." }, "DPoP": { "type": "apiKey", "in": "header", "name": "DPoP", "description": "Fresh caller proof bound to the capability, request, and x402 payment proof." }, "X401Proof": { "type": "apiKey", "in": "header", "name": "PROOF-RESPONSE", "description": "Base64url-encoded x401 principal-identity presentation. Omit to request a proof challenge." }, "bearerAgentSession": { "type": "http", "scheme": "bearer", "bearerFormat": "flint_sess_...", "description": "Agent session bearer token minted by POST /api/auth/otp-verify (Authorization: Bearer flint_sess_...). Accepted everywhere a WorkOSOwnerSession cookie is accepted, so an MCP agent never needs a browser. Also accepted via the X-FLINT-Session header." } }, "parameters": { "RecordId": { "name": "record_id", "in": "path", "required": true, "description": "FLINT verification record identifier.", "schema": { "type": "string", "pattern": "^frv_[0-9A-HJKMNP-TV-Z]{26}$" } }, "SettlementReceiptId": { "name": "receipt_id", "in": "path", "required": true, "description": "FLINT x402 settlement receipt identifier.", "schema": { "type": "string", "pattern": "^fsr_[0-9A-HJKMNP-TV-Z]{26}$" } } }, "headers": { "FlintVerdict": { "description": "FLINT's 4-state transaction-time decision.", "schema": { "$ref": "#/components/schemas/VerdictDecision" } }, "FlintScore": { "description": "FLINT score from 0 through 100.", "schema": { "type": "string", "pattern": "^(?:100|[1-9]?[0-9])$" } }, "PaymentRequired": { "description": "Base64url-encoded canonical x402 v2 payment challenge.", "schema": { "type": "string" } }, "PaymentResponse": { "description": "Base64url-encoded canonical x402 v2 settlement response.", "schema": { "type": "string" } }, "X401ProofRequest": { "description": "Base64url-encoded x401 proof request.", "schema": { "type": "string" } }, "X401ProofResult": { "description": "Base64url-encoded x401 verification result.", "schema": { "type": "string" } } }, "responses": { "MethodNotAllowed": { "description": "HTTP method not allowed for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "X402PaymentRequired": { "description": "Canonical x402 v2 payment challenge. No protected or expensive work has executed.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Conflict or idempotency collision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid partner service credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Authenticated partner does not own the signed record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "The cheap caller-admission quota for paid attempts was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadGateway": { "description": "Upstream graph or service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unavailable": { "description": "Service unavailable or not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServerError": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }