OpenPort Protocol: A Security Governance Specification for AI Agent Tool Access Thanks: Stewardship: Accentrust and the OpenPort Protocol authors. Thanks: Correspondence: research@accentrust.com . Genliang Zhu Accentrust Georgia Institute of Technology Chu Wang Accentrust University of Illinois Urbana-Champaign Abstract AI agents increasingly require direct, structured access to application data and actions, but production deployments still struggle to express and verify the governance properties that matter in practice: least-privilege authorization, controlled write execution, predictable failure handling, abuse resistance, and auditability. This paper introduces OpenPort Protocol (OPP), a governance-first specification for exposing application tools through a secure server-side gateway that is model- and runtime-neutral and can bind to existing tool ecosystems. OpenPort defines authorization-dependent discovery, stable response envelopes with machine-actionable agent.* reason codes, and an authorization model combining integration credentials, scoped permissions, and ABAC-style policy constraints. For write operations, OpenPort specifies a risk-gated lifecycle that defaults to draft creation and human review, supports time-bounded auto-execution under explicit policy, and enforces high-risk safeguards including preflight impact binding and idempotency. To address time-of-check/time-of-use drift in delayed approval flows, OpenPort also specifies an optional State Witness profile that revalidates execution-time preconditions and fails closed on state mismatch. Operationally, the protocol requires admission control (rate limits/quotas) with stable 429 semantics and structured audit events across allow/deny/fail paths so that client recovery and incident analysis are deterministic. We present a reference runtime and an executable governance toolchain (layered conformance profiles, negative security tests, fuzz/abuse regression, and release-gate scans) and evaluate the core profile at a pinned release tag using artifact-based, externally reproducible validation. I Introduction Modern AI agents operate by calling tools: structured functions or actions that read data and perform controlled writes in external systems. While early deployments rely on browser automation or one-off internal APIs, production environments require clear and verifiable guarantees: least-privilege access [ 19 ] , tenant isolation, revocation, operational rate limits, and a complete audit trail. OpenPort Protocol (OPP) targets the gap between “agents can call tools” and “tools can be safely exposed in real systems.” The core observation is that tool discovery is not the hard part; authorization and governance are. A safe agent access layer must define the authorization surface, encode risk constraints for write operations, and make every decision auditable and operable. In other words, the “killer test” for production tool exposure is not a tool-list demo, but real-world authorization flows and predictable rate-limit behavior under failure and abuse. Contributions. This paper makes three contributions: 1. A protocol-level specification for secure tool exposure to AI agents, including endpoints, response envelopes, tool metadata, and error taxonomy. 2. A security governance model that combines scopes and policy constraints with a draft-first write pipeline, high-risk safeguards (preflight, idempotency, and an optional state-witness profile for TOCTOU), mandatory audit events, and rate limits/quotas. 3. An engineering methodology for safe open-source evolution via conformance tests, fuzz/abuse regression, and release-gate checks that operationalize protocol invariants. II Problem Statement and Threat Model OpenPort focuses on the security and governance gap between “tool exposure” and “safe tool exposure.” While tool discovery and structured schemas are necessary for agents to interact with applications, they are not sufficient for production deployments. In practice, AI agents are probabilistic callers: they may call the wrong tool, call the right tool with the wrong arguments, retry unexpectedly, or be influenced by untrusted inputs (for example, prompt injection) to perform unsafe actions. Treating agent tool access as “just another API client” fails to capture these operational failure modes. This paper therefore frames the problem as a governance problem: how to expose application data and actions to agents through a narrow, explicitly authorized, rate-limited, and auditable interface that is safe under both malicious abuse and benign agent mistakes. II-A System Model and Trust Boundaries OpenPort assumes a server-side gateway that mediates all agent access to an application. The gateway is the enforcement point responsible for authentication, authorization, rate limiting, audit emission, and write governance. Domain-specific logic and identity models remain behind adapters, allowing products to preserve internal schemas while still adopting a standardized governance surface. We assume the application operator controls the gateway and the admin control plane, and that all external access is over TLS. Agent Runtime / Model OpenPort Gateway authn, authz, drafts, audit, rate limits Private Adapters tenant resolver, domain reads/writes, notifications Application Data + Actions Admin Control Plane issue/revoke keys, approve drafts agent/v1 API calls Trust boundary (server-side enforcement) Fig. 1: System model and trust boundaries. II-B Assets OpenPort treats the following as protected assets: • Agent credentials : agent keys and delegated tokens, including their metadata (key identifiers, issuance time, revocation state). • Tenant/workspace data : the confidentiality of records reachable through read tools and the integrity of state modified by write tools. • Write intent and effects : the correctness of drafts and executions, including protection against replay, duplicates, and unintended side effects. • Audit stream : decision records and execution traces required for incident response and compliance. • Operational budget : rate-limit and quota capacity, including protection against cost amplification (expensive queries, bulk exports, and high-frequency polling). II-C Assumptions The threat model is intentionally pragmatic and matches typical production constraints: • Transport is protected by TLS and the gateway is the single externally reachable enforcement point. • Private adapters and application databases are not directly reachable by the agent runtime. • Attackers may observe agent-visible content (tool descriptions, responses, and error messages) and may cause the agent to retry or to call unintended tools. • Credentials may leak; therefore, OpenPort assumes that revocation, rate limiting, and auditability are required even for valid-looking requests. II-D Adversary Model We consider both malicious and accidental failures that are characteristic of agent tool access: • External attacker : attempts to steal tokens, enumerate tools, or exploit weak authorization checks. • Compromised agent runtime : uses valid credentials to maximize impact (abuse, exfiltration). • Prompt injection / untrusted content : influences an agent to request unsafe actions. • Benign failure : retries, partial failures, and non-idempotent writes causing duplicate effects. • Operator mistakes : overbroad scopes or misconfigured policies that silently increase blast radius. We do not assume the model itself is trustworthy; instead, OpenPort constrains the effects of tool calls by requiring server-side enforcement and reviewable write paths. II-E Key Threats When an application is opened to AI agents, a recurring set of production risks emerges: 1. Token leakage through prompts, logs, repositories, or CI systems. 2. Tenant/workspace boundary bypass due to client-supplied identifiers or inconsistent checks. 3. Tool enumeration and capability leakage where manifests, schemas, or error details reveal privileged capabilities or sensitive fields. 4. Unapproved destructive writes (delete/export/irreversible actions) caused by automation mistakes or prompt injection. 5. Replay and duplicate effects caused by retries, race conditions, or non-idempotent execution. 6. Insufficient auditability where decisions and side effects cannot be reconstructed. 7. Abuse and overload via excessive calls (DoS), expensive operations, or cost amplification. 8. Sensitive data overexposure through error details and logs that inadvertently capture payloads. II-F Security Goals OpenPort Protocol addresses these threats by specifying server-side governance as protocol requirements. Rather than leaving security decisions as “implementation-defined,” OpenPort promotes a small set of verifiable properties that can be tested in conformance suites and enforced in release gates. We state these properties as concrete security invariants: 1. Deny-by-default authorization. A request MUST be denied unless explicitly allowed by server-side scope grants and policy constraints; there is no implicit access. 2. Server-enforced tenant/workspace boundaries. Every read and write MUST be bound to a server-verified tenant/workspace context; client-supplied identifiers MUST NOT be trusted as the boundary. 3. Authorization-dependent discovery. /manifest MUST reflect current authorization: tools, fields, and capabilities that are not permitted MUST NOT be exposed via discovery responses. 4. Immediate revocation. Revoking a key or app MUST take effect immediately on all endpoints; denials due to revocation MUST be audited with a stable reason code. 5. Draft-first writes. Write actions MUST default to creating drafts; direct execution is only permitted when explicitly enabled by policy, and SHOULD be time-bounded. 6. High-risk execution safeguards. High-risk writes SHOULD require step-up confirmation and MUST support preflight impact hashing and idempotency keys to reduce unintended effects. 7. Replay and duplicate protection. For write intents, the pair { appId , idempotencyKey } MUST uniquely identify an execution outcome and MUST be safely de-duplicated. 8. Operable abuse controls. Implementations MUST enforce baseline rate limits and return stable 429 semantics; servers SHOULD include backoff guidance (for example, Retry-After ) and SHOULD support quotas by tool and tenant. 9. Audit-first governance. Allow/deny/fail decisions and execution outcomes MUST emit structured audit events with stable reason codes and incident-response metadata (for example, key/app identifiers and request metadata). 10. Data minimization. Logs, error details, and audit payloads SHOULD redact sensitive fields and MUST NOT contain secrets such as bearer tokens. TABLE I: Threats and required controls in OpenPort. Threat Required protocol controls Token leakage Revocation, short-lived execution windows, rate limits, audit on every decision Cross-tenant access Server-side tenant resolver; deny-by-default; policy constraints; no client-trusted tenant IDs Tool enumeration AuthZ-dependent manifest; schema and error redaction; deny-by-default exposure Destructive write misuse Draft-first default; step-up confirmation; human approval chain; explicit risk tiers Replay / duplicates Idempotency keys; execution de-duplication per app and key Audit gaps Structured allow/deny/fail audit events with stable reason codes and request metadata Abuse / DoS Per-key/per-IP rate limiting; quotas by tool; predictable 429 behavior Sensitive logging Redaction rules; separation of operational logs vs immutable audit stream II-G Non-goals OpenPort does not replace product identity systems, and it does not guarantee safety against a malicious administrator who controls the gateway and the admin plane. It also does not attempt to solve general prompt safety; instead, it constrains the effects of tool calls via governance requirements (least privilege, reviewable writes, and audited decisions). III Protocol Overview III-A Design Principles OpenPort is designed as a governance-first protocol surface: it standardizes the controls that must hold when exposing application data and actions to probabilistic callers (agent runtimes) rather than assuming a fully correct client. Its core principles are: (i) authorization-dependent, machine-readable tool discovery; (ii) server-side enforcement of authorization, policy constraints, and risk controls; (iii) stable, parseable response envelopes and agent.* reason codes so failures are operable; and (iv) a narrow write interface that defaults to reviewable drafts and can be strengthened with high-risk safeguards (preflight hashing, idempotency, and optional state-witness preconditions). Operationally, OpenPort treats admission control and auditability as first-class requirements: requests must be rate limited/quota controlled and every allow/deny/fail path must be reconstructable from structured audit events. The protocol is domain-extensible: products implement domain reads and actions via adapters, while OpenPort fixes the governance semantics that must remain consistent across domains. Figure 2 summarizes this separation: OpenPort specifies governance semantics and a stable server-side interface, while compatibility with existing tool ecosystems is achieved through optional bindings rather than by delegating enforcement to each ecosystem. Bindings are informative and are evaluated separately from the core conformance claims in this paper. Tool Ecosystems / Runtimes MCP clients \bullet WebMCP pages \bullet custom SDKs OpenPort Protocol (Core) authZ-dependent discovery \bullet stable envelopes draft-first writes \bullet rate limits \bullet audit OpenPort Deployment gateway \bullet admin plane \bullet adapters bindings (optional) server-side enforcement Fig. 2: OpenPort separates governance semantics from tool ecosystems: compatibility is achieved via optional bindings. III-B Versioning and Compatibility OpenPort uses explicit versioning in its URL path (for example, agent/v1 ) to support long-lived clients. Within a major version, servers SHOULD evolve the protocol in a backward-compatible manner (additive fields, additive tools, and stricter governance defaults that remain safe for existing clients). Clients SHOULD ignore unknown fields and treat tool discovery as dynamic, because permitted tools and schemas may change with scopes, policy constraints, and incident response actions such as revocation. III-C Core Objects OpenPort standardizes a small set of objects used by both the protocol and governance layer: • Integration App : a managed integration configuration with scopes and policy. • Agent Key : a revocable token bound to an app (stored as a hash server-side). • Tool : a machine-readable description of an action or read operation, including schemas and governance metadata. • Draft : a reviewable representation of a requested write action. • Execution : the outcome of executing a draft or an allowed write action. • Audit Event : an immutable record of allow/deny/fail decisions and executions. III-D Tool Manifest OpenPort treats tool discovery as an authorization-sensitive API. The agent runtime fetches GET /api/agent/v1/manifest to obtain the integration identity and a list of tools permitted under the presented credential. Each tool includes governance metadata (required scopes, risk tier, and confirmation requirements) and machine-readable schemas for inputs and outputs. The manifest MAY include HTTP hints (method and path) to support runtimes that want to provide clickable traces or debugging output, but correctness MUST NOT depend on clients calling arbitrary paths. Because the manifest is agent-visible, it MUST avoid capability leakage: tools and fields that are not authorized for the current integration MUST NOT appear, and error details SHOULD be redacted to avoid revealing privileged names. Formally, let \mathcal{T} be the global set of tools, let \mathrm{ReqScopes}(t) be the required scope set for tool t , and let \mathrm{Scopes}(a) be the scopes granted to integration app a . Let \mathrm{PolicyAllows}(a,t) denote a predicate that captures additional policy constraints on exposure (for example, field redaction and disabled capabilities). OpenPort defines the visible tool set as: \displaystyle\mathrm{VisibleTools}(a)=\{t\in\mathcal{T}\mid{} \displaystyle\mathrm{ReqScopes}(t)\subseteq\mathrm{Scopes}(a) (1) \displaystyle\wedge\ \mathrm{PolicyAllows}(a,t)\}. This equation expresses the core “authorization-dependent discovery” requirement: discovery output is a function of current authorization state, not a static listing. OpenPort uses a small, opinionated risk scale to support consistent governance. Low risk tools are typically read-only or trivially reversible operations; medium risk tools perform write operations that are expected to be reversible or bounded; and high risk tools include destructive writes, bulk exports, or other actions with significant blast radius. Risk tier is part of tool metadata to support both server-side enforcement (draft-first defaults and high-risk safeguards) and client-side UX (when to request preflight, how to explain required approvals). ⬇ { "name" : "transaction.hard_delete" , "description" : "Permanently delete a transaction." , "requiredScopes" : [ "transaction.delete" ], "risk" : "high" , "requiresConfirmation" : true , "http" : { "method" : "POST" , "path" : "/api/agent/v1/actions" }, "inputSchema" : { "type" : "object" , "properties" : { "payload" : { "type" : "object" } } }, "outputSchema" : { "type" : "object" , "properties" : { "deleted" : { "type" : "object" } } } } Listing 1: Conceptual tool object in OpenPort manifest. III-E Core Endpoints OpenPort defines a minimal agent-facing protocol surface: ⬇ GET / api / agent / v1 / manifest GET / api / agent / v1 / ledgers GET / api / agent / v1 / transactions POST / api / agent / v1 / preflight POST / api / agent / v1 / actions GET / api / agent / v1 / drafts /{ id } Listing 2: OpenPort Protocol agent/v1 endpoints (conceptual). Read endpoints (for example, /ledgers , /transactions ) are illustrative; implementations MAY expose additional domain reads as long as they follow the stable envelope, enforce the same authorization model, and emit audit events. In contrast, writes are intentionally funneled through a small number of governance-aware endpoints. An admin control plane is required for safe operation and is described below. III-F Domain Extensibility and Adapters OpenPort intentionally separates governance semantics from domain semantics . Domain adapters implement product-specific reads and actions (for example, accounting, CRM, ticketing) and translate them into the OpenPort tool model. This boundary has two protocol consequences: • Extensible reads. Implementations MAY add new read endpoints, but each MUST be declared (directly or indirectly) through authorization-dependent discovery and MUST enforce the same scope/policy/tenant controls as core endpoints. • Centralized writes. Implementations SHOULD route writes through a small number of governance-aware endpoints (for example, /preflight and /actions ) so that draft-first, step-up, idempotency, and audit behavior remains consistent across all write tools. In the reference runtime, this takes the form of a tool registry that binds each tool name to an adapter-backed function and attaches governance metadata (required scopes, risk tier, and optional impact computation). III-G Admin Control Plane (Required) OpenPort relies on a human-managed admin control plane to close the authorization loop. While product identity is out of scope, production deployments require a minimal set of governance actions: • create and revoke integration apps and keys (issuance and rotation) • update policy constraints and auto-execute windows • list, approve, and reject drafts • export audit events and operational summaries This admin plane is also the natural place to enforce organizational procedures (for example, separation of duties) and to integrate with incident response workflows. III-H Write Lifecycle: Preflight, Drafts, Execution OpenPort separates three phases of write operations: • Preflight ( POST /preflight ) optionally computes an impact summary and returns an impact hash that can be bound to later execution. Under an optional stronger governance profile, preflight MAY also return a stateWitnessHash that binds execution to a server-observed resource version/state. Implementations MAY also return a short-lived preflight handle ( preflightId ) that allows clients to reuse the exact payload and hash without resending or regenerating content. High-risk policies may require preflight. • Request ( POST /actions ) submits a tool name and payload, and produces either a draft (default) or an execution result (when explicitly permitted). • Review/Execute occurs via the admin plane for draft approval, followed by execution under policy constraints (idempotency, preflight hash binding, and step-up requirements). Drafts expose a stable status model (for example, draft, confirmed, canceled, failed) and are queryable via GET /drafts/{id} . This allows agent runtimes to treat writes as asynchronous and reviewable by design. III-H 1 Preflight Hash Binding Preflight binds execution to a computed impact summary by returning a stable digest over canonical inputs. Let H(\cdot) be a cryptographic hash function and let \mathcal{C}(\cdot) be a deterministic canonical encoding (for the reference profile, RFC 8785 JSON Canonicalization Scheme (JCS) over JSON values [ 18 ] ). Let I(t,x) be the server-side impact function for tool t and payload x (possibly adapter-backed). OpenPort defines the preflight hash as: h=H\big(\mathcal{C}(t,x,I(t,x))\big). (2) If a policy requires preflight for a request, the server MUST deny execution unless the client supplies a preflight hash that matches the server-computed value in Eq. ( 2 ). To make this binding robust under agent non-determinism, clients SHOULD treat /preflight and /actions as one write intent: do not generate a second payload after preflight. A server MAY provide preflightId as a convenience handle that resolves to the cached payload and hash. Such handles SHOULD be TTL-bound and scoped to the credential context (for example, app/key/actor) that created them. If a preflightId is provided but cannot be resolved (expired, unknown, or wrong credential context), the server SHOULD fail closed with agent.preflight_not_found . III-H 2 State Witness Preconditions (Optional Strong Profile) Preflight hash binding protects against payload non-determinism and intent swapping, but it does not fully address time-of-check to time-of-use (TOCTOU) risks when human approvals are delayed and the underlying world state can change. OpenPort therefore defines an optional stronger governance profile: State Witness / Preconditions . Implementations MAY support this profile. Implementations that claim this profile MUST enforce the preconditions described below when a request or draft is bound to a state witness hash. Let W(t,x) be a server-side witness function that returns a minimal, non-secret snapshot of the relevant resource state for tool t and payload x (for example, an HTTP ETag -like value, a resourceVersion -like field, or an adapter-defined version tuple). OpenPort defines a witness hash: w=H\big(\mathcal{C}(W(t,x))\big). (3) If a draft is bound to w (or a client supplies stateWitnessHash directly), the server MUST recompute the current witness at execution time and MUST fail closed unless the current witness hash matches w . On mismatch, the server MUST deny with a stable reason code agent.precondition_failed and MUST NOT execute side effects. Clients SHOULD treat this as a state change: rerun /preflight , refresh operator approval, and avoid blind retries. This mechanism is specified as an optional profile extension and is evaluated separately from the pinned v0.1.0 core evaluation claims in Section XI . III-H 3 Action Request Schema Action requests use an explicit tool name and a free-form payload whose structure is governed by the tool’s input schema in the manifest. To support safe retries and operational tracing, OpenPort defines optional fields for request correlation and replay protection: ⬇ { "action" : "transaction.hard_delete" , "payload" : { "..." : "..." }, "preflightId" : "pfl_..." , "execute" : true , "forceDraft" : false , "requestId" : "req_..." , "idempotencyKey" : "idem_..." , "justification" : "operator intent for high-risk execution" , "preflightHash" : "sha256(...preflight impact...)" , "stateWitnessHash" : "sha256(...witness...)" } Listing 3: Conceptual OpenPort action request. When preflightId is provided, servers MAY reuse a cached payload and preflight hash, allowing clients to omit payload as long as the resolved payload matches the requested action and credential scope. The server MUST decide whether execution is permitted. If execution is not permitted, the server MUST return a draft and MUST provide a machine-readable denial reason code for the auto-execute request. If an idempotency key is provided and a matching execution already exists, the server SHOULD return the prior execution outcome rather than re-executing the tool, to make agent retries safe. III-H 4 Auto-Execute Eligibility Predicate OpenPort treats auto-execution as an explicit, time-bounded capability. Let a be an integration app, let t be a tool, and let \mathrm{cfg}(a) be the auto-execute configuration state. Let \mathrm{exp}(a,t) denote the configured expiration timestamp for the relevant auto-execute window and let \mathrm{AllowList}(a,t) denote an optional allowlist of tool names. Let \mathrm{Req}(r) be the action request fields (execute, forceDraft, justification, idempotencyKey, and either preflightHash or a preflightId that resolves to one, and optionally stateWitnessHash under the State Witness profile). OpenPort defines an eligibility predicate: \displaystyle\mathrm{AutoExecAllowed}(r)= \displaystyle\mathrm{Req}(r).\mathrm{execute}\wedge\neg\mathrm{Req}(r).\mathrm{forceDraft} (4) \displaystyle\wedge\ \mathrm{Enabled}(\mathrm{cfg}(a),t)\wedge(\mathrm{ts}<\mathrm{exp}(a,t)) \displaystyle\wedge\ \Big(\mathrm{AllowList}(a,t)=\emptyset\ \vee \displaystyle t\in\mathrm{AllowList}(a,t)\Big) \displaystyle\wedge\ \Big(\mathrm{risk}(t)\neq\text{{high}}\ \vee \displaystyle\big(\mathrm{Req}(r).\mathrm{justification}\neq\emptyset\ \wedge \displaystyle\mathrm{HighRiskGuards}(r)\big)\Big), where \mathrm{HighRiskGuards}(r) includes idempotency and preflight requirements when configured, and preflight hash matching uses Eq. ( 2 ). If \mathrm{AutoExecAllowed}(r) is false, the server MUST return a draft and MUST return a stable denial reason code. III-H 5 Idempotency as a Deterministic Execution Map Idempotency is expressed as a deterministic mapping from an integration app and idempotency key to an execution outcome. Let a be an integration app identifier and let k be an idempotency key. OpenPort defines: E(a,k)\to\text{{Execution}}, (5) with the invariant that if E(a,k) is already defined, then subsequent requests carrying the same (a,k) MUST NOT re-execute side effects and SHOULD return the existing execution record. This invariant converts agent retries and partial failures into safe, replayable outcomes. III-H 6 Policy Snapshotting To make approvals and incident response tractable, OpenPort recommends snapshotting the governance-relevant policy inputs at the time a draft is created (for example, required scopes, risk tier, and auto-execute configuration). This supports later review of “what the system believed was permitted” at the time of the request, even if policies change before approval. III-I Response Envelope and Error Taxonomy Every endpoint returns a stable response envelope: • success: { ok: true, code, data } • error: { ok: false, code, message, details? } This stability is a core requirement for agent runtimes that need predictable parsing and recovery strategies. The code field is a stable machine-facing identifier. For operational controls such as rate limiting, servers SHOULD return 429 with backoff guidance (for example, Retry-After ) [ 5 , 15 ] . For authorization denials, servers SHOULD return stable denial codes to support safe retry and operator escalation. OpenPort uses a small error taxonomy to make denial behavior predictable (invalid/expired token, scope or policy denial, unknown/invalid action, preflight required/mismatch/not found, idempotency required/replay, and rate limited). Optional stronger profiles MAY add additional stable denial codes; for example, the State Witness profile introduces agent.precondition_failed when an execute-time precondition does not hold. IV Authorization Model IV-A Token Types OpenPort supports two authorization modes that cover most production deployments: 1. Integration tokens for machine-to-machine access, bound to an integration app/key and constrained by server-side scopes and policy constraints. 2. Delegated tokens for “act on behalf of” flows (for example, OAuth 2.0), which MUST be mapped to minimal OpenPort scopes and policy windows before any tool access is granted. The protocol does not mandate a specific identity provider; it mandates that authorization decisions are made server-side and are auditable. IV-B Credential Presentation and Validation Agent requests present credentials as bearer tokens (for example, Authorization: Bearer ). To minimize leakage impact, OpenPort recommends opaque (reference) tokens that are validated by server-side lookup; if self-contained tokens are used, they SHOULD be short-lived and MUST support immediate revocation. Validation MUST check, at minimum: • token presence and parseability • token revocation and expiration • integration app status (active vs revoked/disabled) • network policy constraints (for example, IP allowlists) when configured • baseline abuse controls (rate limits) to bound impact under leakage Failures MUST return stable denial codes (for example, invalid token, expired token, policy denied, rate limited) so agent runtimes can implement safe retry and operator escalation. IV-C Authorization Decision Algorithm OpenPort constrains authorization to a deterministic decision function. For each request, servers SHOULD evaluate in a fixed order: 1. Authenticate : validate the credential and resolve the integration app. 2. Apply network policy : enforce IP allowlists or other network constraints. 3. Rate limit : apply per-key/per-IP limits to bound abuse. 4. Authorize by scope : ensure the tool’s required scopes are granted to the app. 5. Authorize by policy : apply ABAC-style constraints to restrict the data domain and output surface. 6. Enforce tenant/workspace boundary : verify all domain access is within the app’s permitted boundary. 7. Audit : emit allow/deny/fail events for authenticated requests with stable reason codes and incident-response metadata. This ordering is not cosmetic: it is what makes decisions predictable, testable, and operable. IV-C 1 Formal Authorization Predicate Let a request be r=(\tau,t,x,\mathrm{ip},\mathrm{ts}) where \tau is a credential, t is a tool name, x is the payload, and \mathrm{ip} and \mathrm{ts} are request metadata. Let \mathrm{App}(\tau) resolve the integration app and key for a valid credential. OpenPort defines authorization as the conjunction of server-side predicates: \displaystyle\mathrm{Allow}(r)= \displaystyle\mathrm{Authn}(\tau)\ \wedge\ \mathrm{Net}(\mathrm{ip},\mathrm{App}(\tau))\ \wedge\ \mathrm{RL}(r) (6) \displaystyle\wedge\ \mathrm{ScopeOK}(t,\mathrm{App}(\tau))\ \wedge\ \mathrm{PolicyOK}(t,x,\mathrm{App}(\tau)) \displaystyle\wedge\ \mathrm{BoundaryOK}(t,x,\mathrm{App}(\tau)). To ensure stable reason codes, implementations can map the first failing predicate in the evaluation order to a denial code. If the ordered predicates are (p_{1},\ldots,p_{n}) , the denial index is: i^{\ast}=\min\{i\mid p_{i}(r)=\text{{false}}\}, (7) and the reason code is a deterministic function \mathrm{Code}(p_{i^{\ast}}) . IV-D Least Privilege: Scopes Scopes are static capability labels required by tools (for example, transaction.read , transaction.write ). Tools declare requiredScopes in the manifest. The server MUST enforce deny-by-default scope checks; absence of a required scope implies denial. When multiple scopes are required, the semantics are conjunctive (all required scopes must be present). IV-E Least Privilege: Policy Constraints (ABAC) Policy constraints restrict the data domain and presentation surface beyond what scopes can express. OpenPort models policy as ABAC-style constraints [ 8 ] and treats it as mandatory enforcement state. Typical constraints include: • Network policy : IP allowlists for machine clients. • Data policy : allowed resource sets (for example, allowed ledger IDs or organization IDs), bounded time windows for queries, and field-level redaction toggles for sensitive attributes. Policy MUST be enforced server-side and SHOULD be reflected in discovery responses (for example, hiding tools or fields that would be denied). IV-E 1 A Bounded Query Window Constraint A common production control is bounding query time windows to limit both data exposure and cost amplification. Let d_{\max} be the maximum number of days allowed by policy, and let (s,e) be the effective start and end dates for a request after defaulting missing bounds. OpenPort requires the constraint: \Delta(s,e)=\frac{e-s}{\mathrm{day}}\leq d_{\max}, (8) otherwise the server MUST deny with a policy reason code. IV-E 2 Policy Effects on Output Policy constraints may also restrict the presentation surface of returned data. For example, a policy can disable access to sensitive fields; servers SHOULD implement deterministic redaction so that clients can treat outputs as stable and safe to display. When redaction occurs, servers SHOULD disclose which fields were redacted using non-sensitive identifiers (for example, field paths) and SHOULD record redaction outcomes in audit events without logging raw sensitive values. This behavior can be formalized as a function that returns both a presented object and a set of redacted field paths: \mathrm{Present}(o,p)\rightarrow(o^{\prime},F), (9) where o is the raw domain object, p is the effective policy, o^{\prime} is the redacted presentation, and F is the set of redacted fields. IV-F Tenant and Workspace Boundary Enforcement Tenant isolation is a protocol requirement, not an implementation detail. In multi-tenant deployments, an integration app may be scoped to a specific workspace/organization. Servers MUST enforce this boundary using server-side resolution (for example, by fetching resource metadata through adapters) and MUST NOT trust client-provided tenant identifiers as the source of truth. When policies restrict allowed organizations or resource IDs, those checks MUST compose with workspace boundaries. IV-G Reason Codes and Error Semantics OpenPort requires stable reason codes for denials so that agent runtimes can implement safe behavior (refresh discovery, request approval, back off, or escalate to an operator). Reason codes SHOULD be scoped and human-interpretable (for example, agent.token_invalid , agent.scope_denied , agent.policy_denied , agent.rate_limited ), and MUST avoid embedding secrets or internal identifiers. OpenPort standardizes a minimum set of agent.* codes for interoperability; implementations MAY extend with additional codes as long as existing semantics remain stable. For requests that fail before an integration app can be resolved (for example, missing/invalid token), implementations MAY prefer aggregate security metrics over per-request audit events to avoid log amplification; for authenticated requests, auditability is mandatory. IV-H Lifecycle: Issuance, Rotation, Revocation Production authorization requires full lifecycle support: key issuance, parallel keys for rotation, and revocation that is effective immediately. Credentials SHOULD support metadata useful for operations (token prefix, last-used timestamps, expiration) without exposing secrets. IV-H 1 Issuance An integration app is provisioned with an explicit scope set and policy constraints. Keys are issued to apps and SHOULD be displayed only once at issuance; servers SHOULD store only a non-reversible form of the secret (for example, a hash). IV-H 2 Rotation Rotation SHOULD allow parallel validity windows (old and new keys) to avoid downtime and to support staged rollout. Servers SHOULD provide stable key identifiers (not secrets) so operators can audit which credentials were used. IV-H 3 Revocation and Emergency Disablement Revocation MUST take effect immediately across all endpoints, including discovery. OpenPort treats revocation as a first-class security control: denials due to revocation MUST generate audit events with stable reason codes. Implementations SHOULD support an emergency disable switch at the app level to stop all agent access quickly during an incident response. V Authorization Flows This section specifies the expected end-to-end authorization flows that make OpenPort deployable in production. The goal is not to prescribe an identity system, but to define an authorization closed loop : issuance, use, decision logging, and revocation. V-A Provisioning, Issuance, and Tool Discovery (Integration Tokens) An operator provisions an integration app with explicit scopes and policy constraints, then issues an agent key. The agent runtime uses the key to discover permitted tools via the manifest. Discovery is part of the authorization surface: the manifest MUST be authorization-dependent (Eq. ( 1 )) and MUST not leak tools or sensitive fields that are not permitted for the current integration. ⬇ Admin -> Admin API : POST / api / agent - admin / v1 / apps ( scopes , policy ) Admin -> Admin API : POST / api / agent - admin / v1 / apps /{ id }/ keys ( rotate / issue ) Agent -> Agent API : GET / api / agent / v1 / manifest ( Bearer key ) Server -> Audit : allow / deny + code + keyId / appId Fig. 3: Integration token provisioning and authorized tool discovery. V-B Authorized Reads and Policy Effects After discovery, the agent runtime calls read endpoints to retrieve data. Read access is governed by the same decision algorithm (Eq. ( 6 )) and MUST enforce tenant/workspace boundaries and ABAC constraints (resource allowlists, bounded query windows, and redaction). When policies disable sensitive fields, servers SHOULD redact deterministically and SHOULD disclose redacted field paths as in Eq. ( 9 ). ⬇ Agent -> Agent API : GET / api / agent / v1 / ledgers Server -> Audit : allow / deny + code + resultCount Agent -> Agent API : GET / api / agent / v1 / transactions ? ledgerId =... Server -> Audit : allow / deny + code + redactedFields Fig. 4: Authorized reads with policy enforcement and audit emission. V-C Request Evaluation and Reason Codes For each request, OpenPort requires server-side evaluation in a fixed order: authentication (token validity), scope matching, policy constraints (ABAC), and tenant/workspace boundary enforcement. Each denial SHOULD map to a stable reason code (for example, agent.token_invalid , agent.token_expired , agent.scope_denied , agent.policy_denied , agent.forbidden , agent.rate_limited ). These codes enable safe agent retry behavior, operator debugging, and security analytics without exposing sensitive internal details. V-D Write Requests: Draft-First and Optional Auto-Execute Write requests are submitted via POST /api/agent/v1/actions . OpenPort requires draft-first behavior: in the absence of explicit, time-bounded policy enablement, write requests MUST produce drafts rather than execute side effects. Auto-execute eligibility is governed by Eq. ( 4 ) and is designed to be auditable and safely reversible through revocation. For high-risk tools, the agent runtime SHOULD call POST /api/agent/v1/preflight to obtain an impact summary and hash (Eq. ( 2 )) before requesting execution. If auto-execution is denied (disabled, expired, allowlist mismatch, missing justification, missing idempotency, or preflight mismatch), the server MUST return a draft and a machine-readable denial code so operators can decide whether to approve. If an idempotency key is present and a prior execution exists for the same (\text{{appId}},\text{{idempotencyKey}}) , the server SHOULD return the prior execution outcome (Eq. ( 5 )) to make retries safe. ⬇ Agent -> Agent API : POST / api / agent / v1 / preflight ( action , payload ) Server -> Agent : impact , impactHash , preflightId , stateWitnessHash ? Agent -> Agent API : POST / api / agent / v1 / actions ( execute ?, idem ?, preflightHash ?, preflightId ?, stateWitnessHash ?) Server -> Agent : Draft ( default ) or Execution ( if allowed ) Server -> Audit : allow / deny + code + draftId / executionId Fig. 5: Write request flow with optional preflight and draft-first defaults. V-E Admin Review and Execution Drafts provide a reviewable representation of write intent. The admin control plane lists drafts, inspects context (including policy snapshots), and approves or rejects requests. Approval triggers execution under the recorded policy constraints; rejection cancels the draft. This human-in-the-loop step is a governance requirement for high-risk operations and is the primary mechanism to mitigate prompt-injection-driven misuse. OpenPort supports asynchronous client behavior by allowing agents to poll draft status: ⬇ GET / api / agent / v1 / drafts /{ id } GET / api / agent - admin / v1 / drafts ? status = draft POST / api / agent - admin / v1 / drafts /{ id }/ approve POST / api / agent - admin / v1 / drafts /{ id }/ reject Listing 4: Draft review and polling endpoints (conceptual). Clients SHOULD implement backoff for polling and treat drafts as non-final until an execution outcome is recorded. V-F Rotation, Revocation, and Incident Response Authorization safety requires that credentials can be rotated and revoked without downtime. Rotation issues a new key while keeping the old key valid for a controlled overlap window; revocation invalidates a key or an entire app immediately across all endpoints, including /manifest . Implementations SHOULD support emergency disablement at the app level to stop all agent traffic quickly during an incident. ⬇ Admin -> Admin API : POST / api / agent - admin / v1 / apps /{ id }/ keys ( issue new key ) Agent -> Agent API : use new key ( progressive rollout ) Admin -> Admin API : POST / api / agent - admin / v1 / keys /{ id }/ revoke ( revoke old key ) Agent -> Agent API : old key fails immediately ( agent . token_invalid ) Fig. 6: Key rotation and immediate revocation. V-G Client Recovery Guidance Stable reason codes make agent runtimes safer by enabling deterministic recovery logic. Table II summarizes recommended responses for common denial codes. These recommendations are intentionally aligned with the conformance invariants in Table V : a server that satisfies the invariants should enable clients to implement Table II without relying on model-specific heuristics. TABLE II: OpenPort reason codes and recommended client behavior (baseline set with optional profile extensions). Reason code Recommended client action agent.token_invalid agent.token_expired Stop; request a new key/token; refresh discovery after re-authentication. agent.scope_denied Refresh /manifest ; request additional scopes only if explicitly approved. agent.policy_denied agent.forbidden Surface to operator; adjust query/window/resource selection; do not retry blindly. agent.action_unknown agent.action_invalid Do not retry blindly; refresh /manifest and validate tool name and input schema. agent.preflight_required agent.preflight_mismatch agent.preflight_not_found Run /preflight and retry with returned hash (or a valid preflightId ); treat mismatch as a change in impact and do not execute blindly. agent.precondition_failed (State Witness profile) Treat as state change (TOCTOU); rerun /preflight to obtain a fresh witness/hash and require renewed operator approval before execution. agent.idempotency_required Generate a stable idempotency key per write intent and retry once. agent.idempotency_replay Treat as success; reuse returned execution outcome; do not re-execute. agent.auto_execute_disabled agent.auto_execute_expired agent.auto_execute_denied Accept draft result; route to admin approval rather than retrying execution. agent.draft_not_found agent.draft_already_final Stop; refresh draft status from the gateway; treat as non-retriable and require operator review. agent.step_up_required agent.step_up_invalid Complete step-up verification through the operator channel and retry within the allowed window. agent.rate_limited Back off; respect Retry-After if present; reduce polling; consider caching /manifest . V-H Delegated Authorization Binding (OAuth 2.0) OpenPort is compatible with delegated “act on behalf of” use cases, commonly implemented via OAuth 2.0 [ 6 ] . However, delegated identity is insufficient without governance: • delegated tokens MUST map to minimal OpenPort scopes; • delegated sessions MUST apply policy windows (time bounds, resource sets, field redaction); • revocation MUST be effective immediately (including user consent withdrawal). The binding MAY use token introspection or local validation, but the resulting authorization decision MUST be enforced server-side and MUST be auditable. ⬇ User -> IdP : OAuth authorize ( consent ) Agent -> IdP : Obtain delegated access token Agent -> Agent API : Call tool ( delegated token ) Server -> AuthZ : Map claims -> scopes + policy window Server -> Audit : allow / deny + reason + subject + appId Fig. 7: Delegated authorization binding: identity plus governance. VI Risk-Gated Writes Write operations are the primary risk surface for agent tooling because they create side effects and are harder to contain than reads. OpenPort therefore treats “write access” as a governed capability rather than a default API behavior. The protocol’s baseline write posture is draft-first : write requests create reviewable drafts unless auto-execution is explicitly enabled and time-bounded. VI-A Draft-First Semantics Write requests are submitted via POST /api/agent/v1/actions using a tool name and a payload (schemas are discovered via the manifest). The server MUST evaluate authorization and policy constraints server-side (Eq. ( 6 )) before any side effects can occur. Authorization failures (invalid token, missing scope, policy denial) remain hard errors with stable reason codes. If the request is authorized but not eligible for immediate execution, the server MUST return a draft. If execution was explicitly requested (for example, execute=true ) but denied by auto-execute policy, the server MUST attach a stable machine-readable denial reason code for the auto-execute request . Clients MAY explicitly force drafting (for example, forceDraft=true ) to require operator review even when an auto-execute window is enabled. This “fail closed into draft” rule converts many unsafe behaviors (tool misuse, prompt injection, retries) into a review queue rather than side effects. ⬇ Agent -> Agent API : POST / api / agent / v1 / actions ( tool , args , execute ?) Server -> Audit : allow / deny + code + risk tier + draftId Server -> Agent : Draft ( default ) or Execution ( if allowed ) Admin -> Admin API : POST / api / agent - admin / v1 / drafts /{ id }/ approve Server -> Target : Execute ( idempotency + optional preflight hash ) Server -> Audit : execution success / fail + executionId Fig. 8: Draft-first write pipeline with approval and high-risk safeguards. VI-B Draft and Execution Objects OpenPort separates intent (draft) from effect (execution). A draft represents a write request that can be reviewed and approved by an operator. An execution represents the outcome of running a tool under enforced constraints. At minimum, a draft record SHOULD include: • identifiers: draftId , appId , keyId , actor identity; • intent: tool name ( actionType ) and payload; • governance: risk tier, auto_execute_requested , optional justification ; • safeguards: optional preflight impact summary and preflightHash , optional idempotencyKey ; • policy snapshot inputs (for example, required scopes and auto-execute configuration) to support review and incident response. Executions SHOULD include an executionId , the associated draftId , a terminal status, and either a result object or an error string, plus timestamps for audit correlation. VI-C Draft Lifecycle and State Machine Drafts are long-lived governance objects and therefore require explicit lifecycle states. The reference runtime uses a small state machine aligned with operational workflows. Table III summarizes the semantics and transitions. TABLE III: Draft lifecycle states and transitions (reference profile). Status Meaning Transitions (trigger) draft Pending operator decision; no side effects have been executed. confirmed (approve or eligible auto-execute), canceled (reject). confirmed Approved for execution; a successful execution outcome should be recorded for completion. failed (execution attempt fails). canceled Rejected by operator; terminal. none. failed Execution attempted and failed; terminal. none. Figure 9 visualizes the same draft state machine. draft Pending operator decision confirmed Approved for execution canceled Rejected (terminal) failed Execution failed (terminal) On success, record an execution outcome (outside draft.status ) approve / eligible auto-execute reject execution fails Fig. 9: Draft lifecycle state machine (reference profile). Clients SHOULD treat draft.status as governance state, not as a substitute for an execution record. For asynchronous operation, clients MAY poll GET /api/agent/v1/drafts/{id} to retrieve the latest draft state and the most recent execution record. VI-D High-Risk Safeguards: Preflight Hashing and Idempotency For high-risk tools, OpenPort supports additional safeguards that make writes predictable under retries and reduce the chance of unintended side effects. These safeguards are used as gates for auto-execution and as evidence for operator review. VI-D 1 Preflight Impact Hash The POST /api/agent/v1/preflight endpoint computes an impact summary and returns an impact hash. The preflight hash binds the action, payload, and impact summary using Eq. ( 2 ). Clients supply this value as preflightHash in subsequent POST /api/agent/v1/actions requests. When preflight is required for auto-execution, the server MUST deny auto-execution unless the client supplies a matching hash; denial codes include agent.preflight_required and agent.preflight_mismatch . When a deployment offers a preflight handle ( preflightId ) and the handle cannot be resolved, it SHOULD fail closed with agent.preflight_not_found rather than executing with a regenerated payload. This makes high-risk writes robust to agent retries and “time-of-check/time-of-use” confusion: the execution request is tied to the reviewed impact summary, not to an implicit UI interpretation. VI-D 2 Idempotency and Replay Idempotency converts an unsafe retry pattern into a deterministic map (Eq. ( 5 )). If a request carries an idempotency key and an execution already exists for the same (\text{{appId}},\text{{idempotencyKey}}) , the server SHOULD return the prior execution outcome and MUST NOT re-execute side effects. The reference profile uses agent.idempotency_replay for this case, enabling clients to treat the response as a success path. If high-risk auto-execution is enabled but an idempotency key is missing, the server MUST fail closed into a draft and return agent.idempotency_required . VI-E Time-Bounded Auto-Execute (Optional) Auto-execution is an explicit capability that MAY be enabled for a limited time window and tool allowlist. Eligibility is defined by Eq. ( 4 ). If an agent requests execution but \mathrm{AutoExecAllowed}(r) is false, the server MUST return a draft and MUST return a stable denial reason code. In the reference implementation, common denial codes include agent.auto_execute_disabled , agent.auto_execute_expired , and agent.auto_execute_denied ; high-risk guard failures use agent.preflight_required , agent.preflight_mismatch , and agent.idempotency_required . For high-risk auto-execution, the profile also requires a non-empty justification; missing justification is treated as invalid input and returns agent.action_invalid . ⬇ if execute && ! forceDraft : if idempotencyKey && E ( app , idempotencyKey ) exists : return executed ( replayed = true ) compute impact (+ preflight hash ) for high - risk tools denial = AutoExecAllowed ( request ) ? null : < reason code > draft = saveDraft ( status = denial ? " draft " : " confirmed ", snapshot = policyInputs ) audit ( draft , denial ) if denial : return draft ( denial ) execution = executeDraft ( draft ) return executed ( execution ) Listing 5: Server-side decision procedure for POST /actions (conceptual). VI-F Operator Approval and Separation of Duties Draft approval and rejection are performed through an admin control plane (for example, POST /api/agent-admin/v1/drafts/{id}/approve and /reject ). This separation of duties is intentional: the same credentials used for agent access MUST NOT be sufficient to approve high-risk writes. Approval triggers execution with full audit correlation (draftId, executionId, operator identity), and rejection transitions the draft to canceled . Attempts to act on missing or finalized drafts SHOULD return stable denial codes such as agent.draft_not_found and agent.draft_already_final . VII Rate Limits and Abuse Controls Rate limiting is the operational “safety valve” for exposed agent tooling. Even with correct scopes and policies, a compromised key or a runaway agent loop can amplify cost and availability impact through excessive calls, aggressive polling, or repeated retries. OpenPort therefore treats admission control as part of the protocol’s governance surface. VII-A Objectives OpenPort rate limiting and abuse controls target three production objectives: • Bound blast radius under leakage : constrain the maximum request volume per credential and per network origin, so a stolen key cannot rapidly enumerate or exfiltrate data. • Prevent cost amplification : protect expensive endpoints (for example, /actions and /preflight ) from retry storms and polling loops. • Keep behavior predictable : return stable, machine-actionable semantics so agent runtimes can implement deterministic recovery (Table II ) and conformance tests can verify consistent 429 behavior (Table V ). VII-B Rate Limit Dimensions and Default Policy At minimum, OpenPort implementations MUST enforce rate limits by the (credential, client IP) tuple. The credential dimension prevents a single integration key from overwhelming the system; the IP dimension reduces abuse from shared or spoofed credentials and provides a coarse network control. More granular quotas are OPTIONAL but recommended for real deployments: • per integration app ( appId ) to support multiple keys and rotations; • per tenant/workspace/resource to prevent cross-tenant “fan out” even under valid scopes; • per tool/action to assign lower budgets to high-cost operations; • per endpoint class (discovery, reads, writes, polling) so that /manifest and /drafts do not consume the same budget as /transactions . OpenPort does not mandate a specific algorithm, but it requires predictable 429 behavior across these dimensions. Admission control MUST be evaluated before executing any tool logic and before allocating durable governance objects (drafts, executions). In particular, rate-limited requests MUST NOT create drafts or side effects. More generally, let \mathcal{G} denote the set of governance objects created by the write pipeline (drafts and executions). For a request r , define \Delta\mathcal{G}(r) as the newly allocated governance objects during handling of r . OpenPort’s hard-denial posture is: \Delta\mathcal{G}(r)=\emptyset\quad\text{whenever }\neg\mathrm{Allow}(r), (10) which formalizes “no drafts on denials”: authentication failures, scope/policy denials, and admission-control denials must not allocate drafts or executions. VII-C Fixed-Window Admission Rule One simple and testable limiter is a fixed-window admission rule. For a given key identifier k and client IP u , let N_{k,u}(t) be the number of accepted requests in the interval [t-W,t) where W is the window size. The limiter admits a request at time t iff: N_{k,u}(t)