{
  "openapi": "3.1.0",
  "info": {
    "title": "Hybrid ID shared browser session contract",
    "version": "1.1.0",
    "description": "Activated for fresh Hybrid ID sign-ins. Other applications must adopt and verify this contract separately. See browser-sessions.md. Authenticated HTTPS, not an offline signed credential."
  },
  "servers": [
    {
      "url": "https://auth.hybrid-id.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "clientBasic": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "paths": {
    "/sessions/browser": {
      "post": {
        "operationId": "browserSession",
        "security": [
          {
            "clientBasic": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "subject",
                      "access_token"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "enum": [
                          "enroll"
                        ]
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "access_token": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 4096
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "subject",
                      "session_handle"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "enum": [
                          "status",
                          "activity",
                          "revoke"
                        ]
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "session_handle": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 47
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current app-bound validity; enrollment adds session_handle. Revoke returns revoked:true.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "revision",
                        "authenticated_at",
                        "last_activity_at",
                        "idle_expires_at",
                        "hard_expires_at",
                        "checked_at",
                        "valid_until",
                        "schema",
                        "client_id",
                        "subject",
                        "active",
                        "idle_timeout_seconds",
                        "hard_lifetime_seconds"
                      ],
                      "properties": {
                        "revision": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "authenticated_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "last_activity_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "idle_expires_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "hard_expires_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "checked_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "valid_until": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "schema": {
                          "type": "string",
                          "const": "hybrid.browser-session-policy.v1"
                        },
                        "client_id": {
                          "type": "string"
                        },
                        "subject": {
                          "type": "string"
                        },
                        "active": {
                          "type": "boolean",
                          "const": true
                        },
                        "idle_timeout_seconds": {
                          "type": "integer",
                          "enum": [
                            1800,
                            3600,
                            7200,
                            14400,
                            28800,
                            86400,
                            129600,
                            604800
                          ]
                        },
                        "hard_lifetime_seconds": {
                          "type": "integer",
                          "const": 2592000
                        },
                        "session_handle": {
                          "type": "string",
                          "pattern": "^hbs_[A-Za-z0-9_-]{43}$",
                          "description": "Enrollment only. Confidential server-held credential."
                        }
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "revoked"
                      ],
                      "properties": {
                        "revoked": {
                          "const": true,
                          "type": "boolean"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; server-side JSON only"
          },
          "401": {
            "description": "Invalid application, subject, session or approval"
          },
          "413": {
            "description": "Body exceeds 8192 bytes"
          },
          "503": {
            "description": "Unavailable; never extend access on this response"
          }
        }
      }
    },
    "/sessions/connections": {
      "post": {
        "operationId": "createCortexBrowserConnection",
        "summary": "Bind explicitly consented Cortex scopes to an existing canonical browser session",
        "description": "Confidential registered Cortex client only; no browser Origin. No independent inactivity duration. Handle use requires current native session, grant, scopes and ownership.",
        "security": [
          {
            "clientBasic": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "operation",
                  "kind",
                  "subject",
                  "session_handle",
                  "access_token"
                ],
                "properties": {
                  "operation": {
                    "const": "connect"
                  },
                  "kind": {
                    "enum": [
                      "agent",
                      "company",
                      "messaging",
                      "history",
                      "verification",
                      "disclosure",
                      "identity_binding"
                    ]
                  },
                  "subject": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "session_handle": {
                    "type": "string",
                    "pattern": "^hbs_[A-Za-z0-9_-]{43}$",
                    "writeOnly": true
                  },
                  "access_token": {
                    "type": "string",
                    "maxLength": 4096,
                    "writeOnly": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent, scoped, server-only connection bound to the parent browser session. expires_at is the hard storage deadline, not a promise of authority.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "schema",
                    "kind",
                    "subject",
                    "connection_handle",
                    "expires_at",
                    "policy"
                  ],
                  "properties": {
                    "schema": {
                      "const": "hybrid.browser-connection.v1"
                    },
                    "kind": {
                      "enum": [
                        "agent",
                        "company",
                        "messaging",
                        "history",
                        "verification",
                        "disclosure",
                        "identity_binding"
                      ]
                    },
                    "subject": {
                      "type": "string"
                    },
                    "connection_handle": {
                      "type": "string",
                      "pattern": "^hcsc_[A-Za-z0-9_-]{43}$"
                    },
                    "expires_at": {
                      "type": "integer",
                      "description": "Native hard expiry, epoch milliseconds"
                    },
                    "policy": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "revision",
                        "authenticated_at",
                        "last_activity_at",
                        "idle_expires_at",
                        "hard_expires_at",
                        "checked_at",
                        "valid_until",
                        "schema",
                        "client_id",
                        "subject",
                        "active",
                        "idle_timeout_seconds",
                        "hard_lifetime_seconds"
                      ],
                      "properties": {
                        "revision": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "authenticated_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "last_activity_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "idle_expires_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "hard_expires_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "checked_at": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "valid_until": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "schema": {
                          "type": "string",
                          "const": "hybrid.browser-session-policy.v1"
                        },
                        "client_id": {
                          "type": "string"
                        },
                        "subject": {
                          "type": "string"
                        },
                        "active": {
                          "type": "boolean",
                          "const": true
                        },
                        "idle_timeout_seconds": {
                          "type": "integer",
                          "enum": [
                            1800,
                            3600,
                            7200,
                            14400,
                            28800,
                            86400,
                            129600,
                            604800
                          ]
                        },
                        "hard_lifetime_seconds": {
                          "type": "integer",
                          "const": 2592000
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed request or browser Origin"
          },
          "401": {
            "description": "Invalid confidential client or inactive parent browser session"
          },
          "403": {
            "description": "Wrong client, subject, login, kind or missing/withdrawn scoped consent"
          },
          "503": {
            "description": "Authority unavailable; no positive result"
          }
        }
      }
    }
  }
}
