{
  "openapi": "3.1.0",
  "info": {
    "title": "Hybrid ID Cortex agent inventory and consented creation",
    "version": "1.2.0",
    "description": "Configured Cortex client only. Explicit cortex:agents consent; company mode additionally requires cortex:companies and current company:manage. Existing workload and wallet permissions remain separate. See cortex-agents.md for integration and deployment status. Creation additionally requires cortex:agents:create and key proof; returns no execution permission. See cortex-agent-creation.md. Private automation owner mapping is read/check only; Cortex must separately authorize private profile writes. See cortex-agent-owner.md."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3152",
      "description": "Private Core backchannel; never a browser URL."
    }
  ],
  "paths": {
    "/hybrid/cortex-agents": {
      "post": {
        "operationId": "checkCortexAgentAuthority",
        "security": [
          {
            "cortexClient": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ListRequest"
                  },
                  {
                    "$ref": "#/components/schemas/CheckRequest"
                  },
                  {
                    "$ref": "#/components/schemas/CreateRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current online authority, not an execution grant or public credential. allowed=false is a denial.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Inventory"
                    },
                    {
                      "$ref": "#/components/schemas/Check"
                    },
                    {
                      "$ref": "#/components/schemas/Creation"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid application credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Reconnect or review current consent/authority",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Use POST",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable; never reuse a previous approval",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "This endpoint is private; public/proxied ingress is denied."
          }
        }
      }
    },
    "/hybrid/cortex-agent-owner": {
      "post": {
        "operationId": "checkCortexAutomationAgentOwner",
        "summary": "Map delegated ownership to Cortex subject; no link-write permission",
        "description": "Private loopback only. Current agents:read credential plus current Cortex openid/cortex:agents disclosure consent. Native profile ID is never returned. Cortex must separately authorize writes. Check retries create no identities or Cortex records.",
        "security": [
          {
            "cortexClient": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "developer_token",
                  "agent_id",
                  "operation_id"
                ],
                "properties": {
                  "developer_token": {
                    "type": "string",
                    "writeOnly": true,
                    "pattern": "^hid_dev_[A-Za-z0-9_-]{43}$"
                  },
                  "agent_id": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{32}$"
                  },
                  "operation_id": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{32}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fresh authoritative owner mapping, no-store; explicitly not a write grant.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "schema",
                    "issuer",
                    "client_id",
                    "subject",
                    "owner",
                    "agent_id",
                    "name",
                    "status",
                    "representation",
                    "workspace",
                    "ownership_confirmed",
                    "operation_id",
                    "credential_id",
                    "consent_binding",
                    "checkedAt",
                    "expiresAt",
                    "link_permission_granted"
                  ],
                  "properties": {
                    "schema": {
                      "const": "HYBRID_CORTEX_AUTOMATION_AGENT_OWNER_V1"
                    },
                    "issuer": {
                      "const": "https://auth.hybrid-id.com"
                    },
                    "client_id": {
                      "type": "string"
                    },
                    "subject": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9_-]{43}$"
                    },
                    "owner": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{32}$"
                    },
                    "agent_id": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{32}$"
                    },
                    "name": {
                      "type": "string"
                    },
                    "status": {
                      "const": "ACTIVE"
                    },
                    "representation": {
                      "const": "personal"
                    },
                    "workspace": {
                      "type": "null"
                    },
                    "ownership_confirmed": {
                      "const": true
                    },
                    "operation_id": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{32}$"
                    },
                    "credential_id": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "consent_binding": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "checkedAt": {
                      "type": "integer",
                      "description": "Unix milliseconds"
                    },
                    "expiresAt": {
                      "type": "integer",
                      "description": "Unix milliseconds; no more than checkedAt + 10000"
                    },
                    "link_permission_granted": {
                      "const": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid application or expired/revoked delegation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Missing scope, disclosure consent or current account/agent authority",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown/unowned agent or public/forwarded ingress",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "POST required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Unavailable or expired observation; fail closed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "cortexClient": {
        "type": "http",
        "scheme": "basic",
        "description": "Existing confidential Cortex client ID and secret; user OIDC access token is separately required in the body."
      }
    },
    "schemas": {
      "ListRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation",
          "access_token",
          "subject",
          "workspace",
          "offset"
        ],
        "properties": {
          "operation": {
            "const": "list"
          },
          "access_token": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "type": "string",
            "pattern": "^([a-f0-9]{32})?$"
          },
          "offset": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]{0,5})$",
            "description": "Zero initially; then returned nextOffset as a string. Maximum 100000."
          }
        }
      },
      "CheckRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation",
          "access_token",
          "subject",
          "workspace",
          "agent_id",
          "controller_subject"
        ],
        "properties": {
          "operation": {
            "const": "check"
          },
          "access_token": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "type": "string",
            "pattern": "^([a-f0-9]{32})?$"
          },
          "agent_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "controller_subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          }
        }
      },
      "Agent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "agent_id",
          "name",
          "status",
          "controller_subject",
          "representation",
          "workspace"
        ],
        "properties": {
          "agent_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "name": {
            "type": "string",
            "maxLength": 160
          },
          "status": {
            "enum": [
              "ACTIVE",
              "REVOKED"
            ]
          },
          "controller_subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "representation": {
            "enum": [
              "personal",
              "company"
            ]
          },
          "workspace": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{32}$"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Inventory": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "subject",
          "workspace",
          "checkedAt",
          "expiresAt",
          "items",
          "nextOffset"
        ],
        "properties": {
          "schema": {
            "const": "HYBRID_CORTEX_AGENT_AUTHORITY_V1"
          },
          "subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{32}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "checkedAt": {
            "type": "integer",
            "description": "Unix milliseconds; require a fresh lookup before each use."
          },
          "expiresAt": {
            "type": "integer",
            "description": "At most 10000 milliseconds after checkedAt."
          },
          "items": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/Agent"
            }
          },
          "nextOffset": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          }
        }
      },
      "Check": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "subject",
          "workspace",
          "checkedAt",
          "expiresAt",
          "agent_id",
          "allowed",
          "agent"
        ],
        "properties": {
          "schema": {
            "const": "HYBRID_CORTEX_AGENT_AUTHORITY_V1"
          },
          "subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{32}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "checkedAt": {
            "type": "integer",
            "description": "Unix milliseconds; require a fresh lookup before each use."
          },
          "expiresAt": {
            "type": "integer",
            "description": "At most 10000 milliseconds after checkedAt."
          },
          "agent_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "allowed": {
            "type": "boolean"
          },
          "agent": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Agent"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "CreateRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation",
          "access_token",
          "subject",
          "workspace",
          "statement",
          "proof"
        ],
        "properties": {
          "operation": {
            "const": "create"
          },
          "access_token": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "type": "string",
            "pattern": "^([a-f0-9]{32})?$"
          },
          "statement": {
            "type": "string",
            "maxLength": 2048,
            "description": "JSON CreationStatement; sign canonical JSON with the documented domain prefix."
          },
          "proof": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{86}$"
          }
        }
      },
      "CreationStatement": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "client_id",
          "subject",
          "workspace",
          "operation_id",
          "name",
          "public_key_jwk"
        ],
        "properties": {
          "client_id": {
            "type": "string"
          },
          "subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{32}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "operation_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "public_key_jwk": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kty",
              "crv",
              "x"
            ],
            "properties": {
              "kty": {
                "const": "OKP"
              },
              "crv": {
                "const": "Ed25519"
              },
              "x": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{43}$"
              }
            }
          }
        }
      },
      "Creation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "agent_id",
          "name",
          "controller_subject",
          "workspace",
          "status",
          "classification",
          "replayed",
          "execution_enabled"
        ],
        "properties": {
          "schema": {
            "const": "HYBRID_CORTEX_AGENT_CREATION_V1"
          },
          "agent_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "name": {
            "type": "string",
            "maxLength": 160
          },
          "controller_subject": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "workspace": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{32}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "const": "ACTIVE"
          },
          "classification": {
            "enum": [
              "REAL",
              "SYNTHETIC"
            ]
          },
          "replayed": {
            "type": "boolean"
          },
          "execution_enabled": {
            "const": false
          }
        }
      }
    }
  }
}
