Server API Reference#
Built-in FastAPI server implementing all 17 OpenIntent RFCs.
OpenIntentServer#
FastAPI Application#
Create and configure the FastAPI application.
Database#
Database interface for OpenIntent server.
add_dependency(session: Session, intent_id: str, version: int, dependency_id: str) -> Optional[IntentModel]
Add a dependency to an intent.
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.
Count the number of approved ApprovalRequests for a given action.
Count the number of agents assigned to an intent.
Create a new 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(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 a single access request by ID.
List access requests for an intent.
Get the ACL for an intent (default policy + entries).
Get a single ACL entry by ID.
Get immediate children of an intent.
Get intents that this intent depends on.
Get intents that depend on this intent.
Sum all recorded costs for an intent.
Create a new ACL entry (grant access).
Check if an approved ApprovalRequest exists for a given action.
Check if a specific agent is assigned to an intent.
remove_dependency(session: Session, intent_id: str, version: int, dependency_id: str) -> Optional[IntentModel]
Remove a dependency from an intent.
Remove an ACL entry (revoke access).
set_acl(session: Session, intent_id: str, default_policy: str = 'open', entries: Optional[List[Dict]] = None) -> Dict
Set/replace the ACL for an intent.
update_governance_policy(session: Session, intent_id: str, version: int, policy: Optional[dict]) -> Optional[IntentModel]
Update an intent's governance policy with optimistic concurrency.
Configuration#
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', suspension_default_retry_policy: Optional[dict[str, Any]] = None)
Configuration for the OpenIntent server.
class-attribute
instance-attribute
#
RFC-0026: platform-level default HumanRetryPolicy (serialised dict).
When set, agents that have neither a call-site retry_policy argument nor a
default_human_retry_policy class attribute will inherit this policy for
every request_input() call. Exposed read-only via GET /api/v1/server/config.
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 |