{
  "openapi": "3.1.0",
  "info": {
    "title": "Mementom Partner API",
    "version": "1.0.0",
    "description": "Server-to-server API for anonymous partner relationships and protected-action decisions."
  },
  "servers": [
    { "url": "https://mementom.app/api/v1", "description": "Production" }
  ],
  "security": [
    { "vendorBearer": [] }
  ],
  "tags": [
    { "name": "Configuration" },
    { "name": "Connections" },
    { "name": "Protected actions" },
    { "name": "Entitlements" },
    { "name": "Events" }
  ],
  "paths": {
    "/applications": {
      "post": {
        "tags": ["Configuration"],
        "summary": "Create an application",
        "operationId": "createApplication",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["displayName", "applicationType", "redirectUris", "allowedOrigins"],
                "properties": {
                  "displayName": { "type": "string", "minLength": 2, "maxLength": 120 },
                  "applicationType": { "type": "string", "enum": ["web", "native", "service", "device"] },
                  "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } },
                  "allowedOrigins": { "type": "array", "items": { "type": "string", "format": "uri" } },
                  "branding": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Application created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/assurance-policies": {
      "post": {
        "tags": ["Configuration"],
        "summary": "Create an assurance policy",
        "operationId": "createAssurancePolicy",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "minimumMemkeys"],
                "properties": {
                  "name": { "type": "string" },
                  "minimumMemkeys": { "type": "integer", "minimum": 2 },
                  "recoveryProofs": { "type": "integer", "minimum": 2 }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Policy created" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/response-keys": {
      "post": {
        "tags": ["Configuration"],
        "summary": "Create a response key",
        "operationId": "createResponseKey",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["publicJwk"],
                "properties": {
                  "applicationId": { "type": "string", "pattern": "^app_" },
                  "publicJwk": { "type": "object", "description": "RSA public JWK" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Response key created" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/challenge-tags": {
      "get": {
        "tags": ["Configuration"],
        "summary": "List challenge tags",
        "operationId": "listChallengeTags",
        "responses": {
          "200": {
            "description": "Challenge tags",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "challengeTags": { "type": "array", "items": { "$ref": "#/components/schemas/ChallengeTag" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Configuration"],
        "summary": "Create a challenge tag",
        "operationId": "createChallengeTag",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["key", "displayName", "description", "responseKeyId"],
                "properties": {
                  "key": { "type": "string" },
                  "displayName": { "type": "string" },
                  "description": { "type": "string" },
                  "coverageCount": { "type": "integer", "minimum": 1 },
                  "minimumMemkeys": { "type": "integer", "minimum": 2 },
                  "retryLimit": { "type": "integer", "minimum": 0 },
                  "distinctFromAccess": { "type": "boolean" },
                  "responseKeyId": { "type": "string", "pattern": "^rkey_" },
                  "networkPolicyId": { "type": "string", "pattern": "^npol_" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Challenge tag created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeTag" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/connection-requests": {
      "post": {
        "tags": ["Connections"],
        "summary": "Create a connection request",
        "operationId": "createConnectionRequest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["applicationId", "policyId", "returnUri", "visiblePurpose", "requestedRights", "visibleConsequence", "state"],
                "properties": {
                  "applicationId": { "type": "string", "pattern": "^app_" },
                  "policyId": { "type": "string", "pattern": "^pol_" },
                  "returnUri": { "type": "string", "format": "uri" },
                  "visiblePurpose": { "type": "string" },
                  "requestedRights": { "type": "array", "items": { "type": "string" } },
                  "visibleConsequence": { "type": "string" },
                  "state": { "type": "string" },
                  "opaqueCustomerReference": { "type": ["string", "null"] },
                  "authorization": { "$ref": "#/components/schemas/ConnectionAuthorization" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Connection request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionRequest" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/connections/session": {
      "post": {
        "tags": ["Connections"],
        "summary": "Exchange a connection code",
        "operationId": "exchangeConnectionCode",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["applicationId", "code"],
                "properties": {
                  "applicationId": { "type": "string", "pattern": "^app_" },
                  "code": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Mementom session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/connections/remove": {
      "post": {
        "tags": ["Connections"],
        "summary": "Remove a connection",
        "operationId": "removeConnection",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["vendorSubjectId"],
                "properties": { "vendorSubjectId": { "type": "string", "pattern": "^vsub_" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Connection removed" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/challenges": {
      "post": {
        "tags": ["Protected actions"],
        "summary": "Create a challenge",
        "operationId": "createChallenge",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChallengeRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } },
          "202": { "description": "Additional Mementom setup required" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/decisions/retrieve": {
      "post": {
        "tags": ["Protected actions"],
        "summary": "Retrieve a decision",
        "operationId": "retrieveDecision",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["resultId"],
                "properties": { "resultId": { "type": "string" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Encrypted decision envelope" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/decisions/consume": {
      "post": {
        "tags": ["Protected actions"],
        "summary": "Consume a decision",
        "operationId": "consumeDecision",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["resultId", "nonce"],
                "properties": {
                  "resultId": { "type": "string" },
                  "nonce": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Decision consumed" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/entitlements/grant": {
      "post": {
        "tags": ["Entitlements"],
        "summary": "Grant an entitlement",
        "operationId": "grantEntitlement",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EntitlementRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Existing entitlement updated" },
          "201": { "description": "Entitlement created" },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/entitlements/remove": {
      "post": {
        "tags": ["Entitlements"],
        "summary": "Remove an entitlement",
        "operationId": "removeEntitlement",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EntitlementRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Entitlement removed" },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/webhooks": {
      "post": {
        "tags": ["Events"],
        "summary": "Create a webhook endpoint",
        "operationId": "createWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["endpointUrl"],
                "properties": { "endpointUrl": { "type": "string", "format": "uri" } }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Webhook endpoint created; signing secret returned once" },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/events": {
      "get": {
        "tags": ["Events"],
        "summary": "List vendor events",
        "operationId": "listEvents",
        "responses": {
          "200": { "description": "Recent vendor events" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/audit": {
      "get": {
        "tags": ["Events"],
        "summary": "List audit events",
        "operationId": "listAuditEvents",
        "parameters": [
          { "name": "connectionId", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Sanitized audit events" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "vendorBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "vnd_{id}.{clientSecret}"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Vendor authentication required",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource unavailable",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Conflict": {
        "description": "Request conflict",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "Application": {
        "type": "object",
        "required": ["applicationId", "vendorId", "displayName", "applicationType", "status"],
        "properties": {
          "applicationId": { "type": "string", "pattern": "^app_" },
          "vendorId": { "type": "string", "pattern": "^vnd_" },
          "displayName": { "type": "string" },
          "applicationType": { "type": "string" },
          "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } },
          "allowedOrigins": { "type": "array", "items": { "type": "string", "format": "uri" } },
          "branding": { "type": "object" },
          "status": { "type": "string" }
        }
      },
      "ChallengeTag": {
        "type": "object",
        "properties": {
          "challengeTagId": { "type": "string", "pattern": "^ctag_" },
          "vendorId": { "type": "string", "pattern": "^vnd_" },
          "key": { "type": "string" },
          "displayName": { "type": "string" },
          "description": { "type": "string" },
          "responseKeyId": { "type": "string", "pattern": "^rkey_" },
          "status": { "type": "string" },
          "version": { "type": "integer" }
        }
      },
      "ConnectionRequest": {
        "type": "object",
        "properties": {
          "requestId": { "type": "string", "pattern": "^creq_" },
          "connectionRequestToken": { "type": "string" },
          "consumerUrl": { "type": "string", "format": "uri" },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "Session": {
        "type": "object",
        "properties": {
          "tokenType": { "const": "MementomSession" },
          "sessionId": { "type": "string" },
          "vendorSubjectId": { "type": "string", "pattern": "^vsub_" },
          "identityAttributes": { "type": "object", "maxProperties": 0 },
          "resultId": { "type": "string", "pattern": "^result_", "description": "Present only when the connection request carried a bound authorization." },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "ConnectionAuthorization": {
        "type": "object",
        "required": ["challengeTagId", "gateRequestId", "action", "resourceDigest", "visibleDetails"],
        "properties": {
          "challengeTagId": { "type": "string", "pattern": "^ctag_" },
          "gateRequestId": { "type": "string" },
          "action": { "type": "string" },
          "resourceDigest": { "type": "string", "description": "SHA-256 digest" },
          "visibleDetails": {
            "type": "object",
            "required": ["resourceSummary", "consequence", "expiresAt"],
            "properties": {
              "actionLabel": { "type": "string" },
              "resourceSummary": { "type": "string" },
              "consequence": { "type": "string" },
              "expiresAt": { "type": "string", "format": "date-time" }
            }
          }
        },
        "description": "Optional protected action completed by the same proof that establishes the connection."
      },
      "ChallengeRequest": {
        "type": "object",
        "required": ["applicationId", "sessionId", "challengeTagId", "gateRequestId", "state", "action", "resourceDigest", "visibleDetails", "returnUri"],
        "properties": {
          "applicationId": { "type": "string", "pattern": "^app_" },
          "sessionId": { "type": "string" },
          "challengeTagId": { "type": "string", "pattern": "^ctag_" },
          "gateRequestId": { "type": "string" },
          "state": { "type": "string" },
          "action": { "type": "string" },
          "resourceDigest": { "type": "string", "description": "SHA-256 digest" },
          "visibleDetails": {
            "type": "object",
            "required": ["resourceSummary", "consequence"],
            "properties": {
              "actionLabel": { "type": "string" },
              "resourceSummary": { "type": "string" },
              "consequence": { "type": "string" },
              "expiresAt": { "type": "string", "format": "date-time" }
            }
          },
          "returnUri": { "type": "string", "format": "uri" }
        }
      },
      "Challenge": {
        "type": "object",
        "properties": {
          "challengeId": { "type": "string", "pattern": "^chal_" },
          "gateRequestId": { "type": "string" },
          "challengeUrl": { "type": "string", "format": "uri" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "idempotentReplay": { "type": "boolean" }
        }
      },
      "EntitlementRequest": {
        "type": "object",
        "required": ["vendorSubjectId", "challengeTagId"],
        "properties": {
          "vendorSubjectId": { "type": "string", "pattern": "^vsub_" },
          "challengeTagId": { "type": "string", "pattern": "^ctag_" },
          "expiresAt": { "type": ["string", "null"], "format": "date-time" }
        }
      }
    }
  }
}