{
  "openapi": "3.1.0",
  "info": {
    "title": "Hybrid-ID owner-device Vault API",
    "version": "2026-10-20",
    "description": "Deployed and verified using five API-only synthetic owners on hybrid-mainnet, independently of MPC wallets. Native owner credentials and cryptography remain on the owner device. No browser/HTML/cookie dependency. The body union defines outer fields; native encrypted protection and selected-file validators remain authoritative. Each production client registers its own exact HTTPS origin and callback."
  },
  "servers": [
    {
      "url": "https://auth.hybrid-id.com"
    }
  ],
  "paths": {
    "/vault/owner": {
      "post": {
        "operationId": "partnerVaultOwnerCommand",
        "summary": "API-only owner enrollment, protection and explicit application/file consent",
        "description": "Anonymous register follows existing Hybrid-ID public signup policy. Every other operation requires a current native hcb owner bearer from a web-platform API session; this credential class does not require a browser. App secrets and app-scoped tokens are not owner authentication. Server derives owner context. Fresh purpose-bound MFA and exact terms protect consent. Unknown fields, browser Origin and query parameters are rejected. Responses are no-store. Receipt-only server renewals live at the separate confidential file API.",
        "security": [
          {},
          {
            "nativeOwner": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "register"
                      },
                      "email": {
                        "type": "string",
                        "format": "email"
                      },
                      "password": {
                        "type": "string",
                        "writeOnly": true
                      },
                      "first_name": {
                        "type": "string"
                      },
                      "last_name": {
                        "type": "string"
                      },
                      "terms_version": {
                        "type": "string"
                      },
                      "terms_accepted": {
                        "const": true
                      }
                    },
                    "required": [
                      "operation",
                      "email",
                      "password",
                      "first_name",
                      "last_name",
                      "terms_version",
                      "terms_accepted"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "authenticator-session"
                      },
                      "device_id": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9._:-]{16,128}$"
                      }
                    },
                    "required": [
                      "operation",
                      "device_id"
                    ],
                    "description": "First MFA only. Uses the existing fixed Hybrid-ID management-session exchange. Returned native management bearer stays on the owner device and is used only for enrollment/confirmation, never on the partner backend."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "protection-status"
                      }
                    },
                    "required": [
                      "operation"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "protection-package"
                      }
                    },
                    "required": [
                      "operation"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "protection"
                      },
                      "command": {
                        "type": "object",
                        "description": "Closed initial enrollment commands: context, step-up, begin or commit. Existing HC_ACCOUNT_SECURITY_V2 package/proof validators apply. No master password or private/root key."
                      }
                    },
                    "required": [
                      "operation",
                      "command"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "application-create"
                      },
                      "request_id": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{32}$"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "Name, exact HTTPS callback lists, vault_enabled=true and recipient public key only."
                      },
                      "step_up_token": {
                        "type": "string",
                        "writeOnly": true
                      }
                    },
                    "required": [
                      "operation",
                      "request_id",
                      "metadata",
                      "step_up_token"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "connection-preview"
                      },
                      "client_id": {
                        "type": "string"
                      },
                      "scopes": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 2,
                        "uniqueItems": true,
                        "items": {
                          "enum": [
                            "vault:files:upload",
                            "vault:files:read"
                          ]
                        }
                      }
                    },
                    "required": [
                      "operation",
                      "client_id",
                      "scopes"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "connection-authorize"
                      },
                      "client_id": {
                        "type": "string"
                      },
                      "scopes": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 2,
                        "uniqueItems": true,
                        "items": {
                          "enum": [
                            "vault:files:upload",
                            "vault:files:read"
                          ]
                        }
                      },
                      "request_id": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{32}$"
                      },
                      "preview_digest": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      },
                      "step_up_token": {
                        "type": "string",
                        "writeOnly": true
                      },
                      "acknowledgement": {
                        "const": "AUTHORIZE_THIS_APPLICATION_FILE_ACCESS"
                      }
                    },
                    "required": [
                      "operation",
                      "client_id",
                      "scopes",
                      "request_id",
                      "preview_digest",
                      "step_up_token",
                      "acknowledgement"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "connection-revoke"
                      },
                      "client_id": {
                        "type": "string"
                      },
                      "step_up_token": {
                        "type": "string",
                        "writeOnly": true
                      }
                    },
                    "required": [
                      "operation",
                      "client_id",
                      "step_up_token"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "operation": {
                        "const": "file-review"
                      },
                      "command": {
                        "type": "object",
                        "description": "Closed owner commands list, read, approve, decline and revoke. Decisions require exact request_id, revision, terms_digest and one-use step_up_token; approve additionally requires acknowledgement and the selected file key envelope. No owner selector."
                      }
                    },
                    "required": [
                      "operation",
                      "command"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated operation-specific response in {success:true,response:...}."
          },
          "400": {
            "description": "Malformed or unsupported command."
          },
          "401": {
            "description": "Native owner authentication required or expired."
          },
          "403": {
            "description": "Current owner permission or fresh verification required."
          },
          "404": {
            "description": "Current app/file request not available."
          },
          "409": {
            "description": "Exact terms, pending operation or immutable retry changed."
          },
          "413": {
            "description": "Owner request too large."
          },
          "429": {
            "description": "Rate limit reached."
          },
          "503": {
            "description": "Feature disabled or upstream authority unavailable."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "nativeOwner": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "hcb native owner web-platform API session, never a partner app token"
      }
    }
  }
}