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. Set it explicitly in every environment: when it is unset, alquimia-core has no single default (inference keeps the spec’s connector, ingest and rebuild fall back to qdrant, and version rehydration is skipped). The runtime exports its own default, qdrant, when the variable is unset.

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)