Server API Reference#

Built-in FastAPI server implementing all 17 OpenIntent RFCs.

OpenIntentServer#

OpenIntentServer #

OpenIntentServer(
    host: str = "0.0.0.0",
    port: int = 8000,
    database_url: Optional[str] = None,
    api_keys: Optional[set] = None,
    **kwargs
)

High-level server class for running OpenIntent.

run #

run()

Run the server (blocking).

run_async `async` #

run_async()

Run the server asynchronously.

FastAPI Application#

create_app #

create_app(
    config: Optional[ServerConfig] = None,
) -> FastAPI

Create and configure the FastAPI application.

Database#

Database #

Database(database_url: str)

Database interface for OpenIntent server.

add_dependency #

add_dependency(
    session: Session,
    intent_id: str,
    version: int,
    dependency_id: str,
) -> Optional[IntentModel]

Add a dependency to an intent.

approve_access_request #

approve_access_request(
    session: Session,
    request_id: str,
    decided_by: str,
    permission: Optional[str] = None,
    expires_at: Optional[datetime] = None,
    reason: Optional[str] = None,
) -> Optional[AccessRequestModel]

Approve an access request and create a corresponding ACL entry.

create_access_request #

create_access_request(
    session: Session, **kwargs
) -> AccessRequestModel

Create a new access request.

create_tables #

create_tables()

Create all tables.

deny_access_request #

deny_access_request(
    session: Session,
    request_id: str,
    decided_by: str,
    reason: Optional[str] = None,
) -> Optional[AccessRequestModel]

Deny an access request.

find_agent_grant_for_tool #

find_agent_grant_for_tool(
    session: Session, agent_id: str, tool_name: str
) -> Optional[ToolGrantModel]

Find an active grant for an agent that covers a specific tool/service name.

Matches in priority order: 1. Grant scopes contain the tool name (e.g. scopes=["web_search"]) 2. Grant context has a 'tools' list containing the tool name 3. Credential service matches the tool name exactly

get_access_request #

get_access_request(
    session: Session, request_id: str
) -> Optional[AccessRequestModel]

Get a single access request by ID.

get_access_requests #

get_access_requests(
    session: Session, intent_id: str
) -> List[AccessRequestModel]

List access requests for an intent.

get_acl #

get_acl(session: Session, intent_id: str) -> Dict

Get the ACL for an intent (default policy + entries).

get_acl_entry #

get_acl_entry(
    session: Session, entry_id: str
) -> Optional[ACLEntryModel]

Get a single ACL entry by ID.

get_children #

get_children(
    session: Session, parent_id: str
) -> List[IntentModel]

Get immediate children of an intent.

get_dependencies #

get_dependencies(
    session: Session, intent_id: str
) -> List[IntentModel]

Get intents that this intent depends on.

get_dependents #

get_dependents(
    session: Session, intent_id: str
) -> List[IntentModel]

Get intents that depend on this intent.

get_session #

get_session() -> Session

Get a new database session.

grant_access #

grant_access(
    session: Session,
    intent_id: str,
    granted_by: str,
    **kwargs
) -> ACLEntryModel

Create a new ACL entry (grant access).

remove_dependency #

remove_dependency(
    session: Session,
    intent_id: str,
    version: int,
    dependency_id: str,
) -> Optional[IntentModel]

Remove a dependency from an intent.

revoke_access #

revoke_access(
    session: Session, intent_id: str, entry_id: str
) -> bool

Remove an ACL entry (revoke access).

set_acl #

set_acl(
    session: Session,
    intent_id: str,
    default_policy: str = "open",
    entries: Optional[List[Dict]] = None,
) -> Dict

Set/replace the ACL for an intent.

Configuration#

ServerConfig `dataclass` #

ServerConfig(
    host: str = "0.0.0.0",
    port: int = 8000,
    database_url: Optional[str] = None,
    api_keys: Set[str] = (
        lambda: {
            "dev-user-key",
            "agent-research-key",
            "agent-synth-key",
        }
    )(),
    cors_origins: list = (lambda: ["*"])(),
    debug: bool = False,
    log_level: str = "info",
    protocol_version: str = "0.1",
)

Configuration for the OpenIntent server.

from_env `classmethod` #

from_env() -> ServerConfig

Create configuration from environment variables.

Tool Invocation Endpoint#

The server provides a tool invocation proxy at POST /api/v1/tools/invoke. This endpoint:

Validates the agent has a matching tool grant (3-tier resolution)
Resolves credentials from the vault (never exposed to the agent)
Enforces rate limits on the grant
Selects the appropriate execution adapter based on credential metadata
Executes the tool against the external API (or returns a placeholder if no execution config)
Sanitizes secrets from the response
Records the invocation for audit with a request fingerprint

Request#

{
  "tool_name": "web_search",
  "agent_id": "researcher",
  "parameters": {"query": "OpenIntent protocol"}
}

Response (Real Execution)#

{
  "invocation_id": "inv-abc123",
  "tool_name": "web_search",
  "status": "success",
  "result": {"organic_results": [{"title": "OpenIntent", "link": "..."}]},
  "duration_ms": 342,
  "grant_id": "grant-abc123"
}

Response (Placeholder Fallback)#

When the credential has no execution config (base_url, endpoints), the endpoint returns a placeholder:

{
  "tool_name": "web_search",
  "agent_id": "researcher",
  "result": {"placeholder": true, "tool_name": "web_search"},
  "duration_ms": 1,
  "grant_id": "grant-abc123"
}

Error Responses#

HTTP Status	Meaning
`403`	Grant not found, expired, revoked, or URL validation failed
`429`	Rate limit exceeded
`502`	Upstream service returned a server error
`504`	Upstream service timed out

Grant Resolution Order#

Priority	Source	Match Condition
1	`grant.scopes`	Tool name found in scopes list
2	`grant.context["tools"]`	Tool name found in context tools array
3	`credential.service`	Credential service name matches tool name

Execution Adapters#

Adapter	Auth Types	Triggered When
`RestToolAdapter`	API key, Bearer, Basic Auth	`auth_type` is `api_key`, `bearer_token`, or `basic_auth` and `base_url` present
`OAuth2ToolAdapter`	OAuth2 with token refresh	`auth_type` is `oauth2_token` and `base_url` present
`WebhookToolAdapter`	HMAC-signed dispatch	`adapter` is `webhook` or `auth_type` is `webhook`

Security Controls#

All outbound requests are subject to:

URL validation: Blocks private IPs, cloud metadata endpoints, non-HTTP schemes
Timeout bounds: Clamped to 1–120 seconds
Response size: Capped at 1 MB
Secret sanitization: Keys and tokens replaced with [REDACTED] in outputs
Request fingerprinting: SHA-256 fingerprint stored for audit correlation

CLI#

The server can be started via command line:

# Default options
openintent-server

# Custom host and port
openintent-server --host 0.0.0.0 --port 8080

# With custom database
DATABASE_URL=postgresql://... openintent-server

CLI Options#

Option	Default	Description
`--host`	`0.0.0.0`	Bind address
`--port`	`8000`	Port number
`--reload`	`false`	Enable auto-reload
`--log-level`	`info`	Logging level