Authorization policies

Alquimia Platform uses a Zero Trust authorization model for tools and knowledge. An agent’s role sets a capability ceiling, but fine-grained access is enforced by policy objects that can deny operations or require human approval regardless of what the agent spec says.

Role tiers

Tier	Typical access
`reader`	Read-only tools and non-sensitive knowledge
`editor`	Mutating but recoverable operations
`operator`	Destructive or high-risk actions

system is reserved for the pod identity and cannot be assigned to an agent. The agent’s declared role is a ceiling, not a permission list. A null role receives no tier grants when default_deny is enabled, which is the safe failure mode.

Tool authorization

The active ToolAuthzPolicy is evaluated before the legacy human_approval flag. The production default is DefaultToolAuthzPolicy(default_deny=True).

Decision	Meaning
`ALLOW`	Tool may execute
`REQUIRE_APPROVAL`	Tool pauses for human approval
`DENY`	Tool is rejected immediately

When default_deny=True:

An unclassified tool is denied outright.
An agent whose role tier is not in the operation’s effective tier grants is denied.
A destructive operation always requires approval.

Per-operation classification

A ToolRegistration classifies each operation by name. This is essential for bundled connections such as an MCP server that exposes both reads and writes.

{
  "registered_tool_id": "filesystem-tools",
  "provider_id": "mcp",
  "connection_config": { "url": "http://mcp-server" },
  "operations": [
    { "name": "list_files", "match": "exact", "severity": "read-only", "tier_grants": ["reader", "editor", "operator"] },
    { "name": "delete_*", "match": "glob", "severity": "destructive", "tier_grants": ["operator"] }
  ]
}

Field	Description
`name`	Tool name pattern
`match`	`exact`, `glob`, or `regex` (first match wins)
`severity`	`read-only`, `mutating-recoverable`, or `destructive`
`tier_grants`	Roles allowed to invoke this operation
`approval_required`	Whether human approval is required

Severity floors

Severity acts as a floor on top of tier_grants and approval_required:

Severity	Max grantable tier	Approval
`read-only`	`reader`, `editor`, `operator`	As configured
`mutating-recoverable`	`editor`, `operator` (`reader` excluded)	As configured
`destructive`	`operator` only	Always required

A tool name matching no classified operation is denied outright.

Tier ceiling on the agent spec

An agent spec can narrow the registry’s tier grants for its own use:

{
  "provider_id": "mcp",
  "tool_ref": "filesystem-tools",
  "tier_ceiling": ["reader", "editor"]
}

tier_ceiling intersects with the registry grants; it can never widen them.

Configuring the policy

In Python:

from alquimia.core.authz import DefaultToolAuthzPolicy, set_tool_authz_policy

set_tool_authz_policy(DefaultToolAuthzPolicy(default_deny=True))

Use default_deny=False only in dev/test environments where unregistered raw tools are acceptable.

Knowledge authorization

Knowledge-base queries are evaluated by the active KnowledgeAuthzPolicy before the retriever runs. The default is DefaultKnowledgeAuthzPolicy(default_deny=True).

A TopicRegistration carries an access policy similar to a tool operation:

{
  "topic_id": "product-docs",
  "agentspace_id": "acme",
  "external_collection_id": "acme__product-docs",
  "access_policy": {
    "severity": "read-only",
    "tier_grants": ["reader", "editor", "operator"],
    "approval_required": false
  }
}

When default_deny=True:

An inline collection_id with no resolvable topic_id is denied.
An agent whose role tier is not in the topic’s effective tier grants is denied.
A topic whose policy requires approval blocks on synchronous approval.

Topic resolution and backend selection

When an agent spec uses topic_id, the registry resolves it to external_collection_id and agentspace_id. The underlying collection name is namespaced as {agentspace_id}__{collection_id}, and an agentspace_id metadata filter is injected into every query.

Set ALQUIMIA_KNOWLEDGE_PROVIDER to swap the vector-store backend for every topic-based, connector-backed knowledge base in the process:

export ALQUIMIA_KNOWLEDGE_PROVIDER=redis

This lets the same agent spec run against Qdrant in production and an in-memory store in tests without editing the spec.

Direct file access

search_mode="direct" exposes list_files and read_file tools over a topic’s registered files. The same KnowledgeAuthzPolicy gate applies, so direct mode is not a bypass.

Programmatic policy management

from alquimia.core.authz import (
    DefaultToolAuthzPolicy,
    DefaultKnowledgeAuthzPolicy,
    set_tool_authz_policy,
    set_knowledge_authz_policy,
)

set_tool_authz_policy(DefaultToolAuthzPolicy(default_deny=True))
set_knowledge_authz_policy(DefaultKnowledgeAuthzPolicy(default_deny=True))

Recommended production defaults

# Runtime / worker environment
ALQUIMIA_RUNTIME_MODE=worker

# Core authz policy
# (set in code via set_tool_authz_policy / set_knowledge_authz_policy)
# DefaultToolAuthzPolicy(default_deny=True)
# DefaultKnowledgeAuthzPolicy(default_deny=True)