{
  "openapi": "3.1.0",
  "info": {
    "title": "WhoActs design-partner verification model",
    "version": "0.2.0",
    "description": "An inspectable API contract for scoped WhoActs sandbox demonstrations. This document does not advertise a public production endpoint, service level, certification or qualified trust status.",
    "contact": {
      "name": "Robert Prime",
      "url": "https://whoacts.com/book-demo"
    },
    "x-whoacts-access": "Scoped design-partner sandbox demonstration",
    "x-whoacts-production-status": "Not generally available"
  },
  "externalDocs": {
    "description": "Implementation boundaries and evidence",
    "url": "https://whoacts.com/evidence"
  },
  "tags": [
    {
      "name": "Verification",
      "description": "Evaluate a requested action against signed authority evidence and current mandate policy."
    }
  ],
  "paths": {
    "/api/v1/verifications": {
      "post": {
        "tags": ["Verification"],
        "summary": "Evaluate one requested action",
        "description": "Design-partner contract only. Authentication, issuer trust, status profile and production endpoint are agreed per connected deployment.",
        "operationId": "createVerification",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy decision and inspectable check result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed or incomplete request"
          },
          "401": {
            "description": "Authentication required in a connected deployment"
          },
          "422": {
            "description": "Evidence could be parsed but authority could not be evaluated"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Connected authentication is deployment-specific and is not issued by this public website."
      }
    },
    "schemas": {
      "VerificationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "credential",
          "requestedAction",
          "resource",
          "jurisdiction",
          "channel"
        ],
        "properties": {
          "credential": {
            "type": "string",
            "description": "Signed authority presentation supplied by the holder.",
            "minLength": 1
          },
          "requestedAction": {
            "type": "string",
            "example": "place_purchase_order"
          },
          "resource": {
            "type": "string",
            "example": "procurement-account-17"
          },
          "jurisdiction": {
            "type": "string",
            "example": "DE"
          },
          "channel": {
            "type": "string",
            "example": "api"
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "example": 18500
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "example": "EUR"
          },
          "humanApprovalRecorded": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "VerificationResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["decision", "checks", "reasonCodes", "receiptReference"],
        "properties": {
          "decision": {
            "type": "string",
            "enum": ["PERMITTED", "DENIED", "APPROVAL_REQUIRED"]
          },
          "checks": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/CheckResult"
            }
          },
          "reasonCodes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "receiptReference": {
            "type": "string",
            "example": "vrf_8F31"
          }
        }
      },
      "CheckResult": {
        "type": "string",
        "enum": ["pass", "fail", "not_applicable", "unresolved"]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}