Agent Identity & RBAC: A Practical Guide

Why Agents Need Identity

In traditional software systems, identity is straightforward — users authenticate with credentials and are authorized based on roles. But AI agent systems introduce a new challenge: the agents themselves need identities. A customer support agent should not have access to financial data. A research agent should be able to read data but not delete it. A background analytics agent should have lower resource quotas than a user-facing agent.

Without proper agent identity, every agent runs with the same permissions, accesses the same data, and consumes the same resource pool. This makes it impossible to enforce least-privilege access, attribute actions to specific agents, or prevent a runaway agent from consuming all available resources.

HatiData treats agent identity as a first-class concern. Every agent has a unique identity (represented by an API key), a set of permissions (defined by a key scope), resource quotas (limiting what it can consume), and namespace isolation (controlling what data it can access). Together, these form a comprehensive security model for multi-agent systems.

API Keys and Key Scopes

Every agent authenticates to HatiData using an API key. Keys follow the format hd_live_{random} for production and hd_test_{random} for testing environments. Each key is associated with an organization, an agent name, and a key scope that defines its permissions.

HatiData supports two key scopes:

ReadOnly

ReadOnly keys can query data, search memories, replay reasoning chains, and read agent state. They cannot write memories, log reasoning steps, modify triggers, create branches, or change any data. This scope is appropriate for analytics agents, monitoring tools, and dashboards.

{
  "agent_name": "analytics-dashboard",
  "scope": "readonly",
  "namespaces": ["analytics", "reports"],
  "monthly_credit_limit": 1000
}

Admin

Admin keys have full access to all operations: reading, writing, creating branches, managing triggers, and rotating keys. This scope is appropriate for primary agents that need to interact with the full feature set.

{
  "agent_name": "primary-support-agent",
  "scope": "admin",
  "namespaces": ["customer-support", "product-feedback"],
  "monthly_credit_limit": 10000
}

Note that there is no intermediate "ReadWrite" scope — the design philosophy is that agents either observe (ReadOnly) or fully participate (Admin). This simplifies the permission model and avoids the combinatorial explosion of fine-grained permission flags.

Creating and Managing Agent Keys

Agent keys are created through the control plane API or the HatiData dashboard. The creation request specifies the agent name, scope, allowed namespaces, and resource quotas:

curl -X POST https://api.hatidata.com/v1/keys \
  -H "Authorization: Bearer hd_live_org_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "research-agent-v2",
    "scope": "admin",
    "namespaces": ["research", "papers", "citations"],
    "monthly_credit_limit": 5000,
    "description": "Research agent for academic paper analysis"
  }'

The response includes the new API key (shown only once) and a key ID for management operations:

{
  "key_id": "key_8x9k2m",
  "api_key": "hd_live_rA3bK9...",
  "agent_name": "research-agent-v2",
  "scope": "admin",
  "namespaces": ["research", "papers", "citations"],
  "monthly_credit_limit": 5000,
  "created_at": "2026-03-02T10:00:00Z"
}

Key Rotation

API keys should be rotated regularly as a security best practice. HatiData supports seamless key rotation through the rotate_key operation — either via the API, dashboard, or MCP tool. When a key is rotated:

1. 1A new key is generated with the same scope, namespaces, and quotas
2. 2The old key enters a grace period (default 24 hours) during which both keys are valid
3. 3After the grace period, the old key is permanently invalidated

This grace period allows agents to be updated with the new key without downtime. The rotation is logged in the audit trail with both the old and new key IDs.

Resource Quotas

Every agent key has an associated resource quota that limits its consumption. Quotas prevent runaway agents from consuming disproportionate resources and enable cost attribution per agent.

The ResourceQuota includes:

• monthly_credit_limit — Maximum compute credits the agent can consume per billing month
• used — Current usage within the billing period, updated in real time
• org_id — The organization that owns this quota

When an agent's usage approaches its quota, HatiData emits warnings at 80% and 90% thresholds. At 100%, further queries are blocked until the quota resets at the start of the next billing period or an administrator increases the limit.

-- Agents can check their own quota
SELECT * FROM _hatidata_quota WHERE agent_id = current_agent_id();

Quotas are enforced in the query pipeline's quota check step, before the query reaches the execution engine. This means that quota-blocked queries do not consume any compute resources.

Namespace Isolation

Namespaces are the primary mechanism for data isolation between agents. Each memory, reasoning trace, and state entry belongs to a namespace, and each agent key specifies which namespaces it can access.

When an agent queries data, HatiData automatically applies a namespace filter to ensure the agent only sees data in its allowed namespaces. This happens transparently — the agent does not need to add namespace filters to its queries.

Agent Key: research-agent-v2
Allowed Namespaces: [research, papers, citations]

Query: SELECT * FROM agent_memories WHERE content LIKE '%quantum%'

Executed as: SELECT * FROM agent_memories
             WHERE content LIKE '%quantum%'
             AND namespace IN ('research', 'papers', 'citations')

Namespace isolation also applies to MCP tools. When the research agent calls store_memory, it can only write to the research, papers, or citations namespaces. Attempting to write to a different namespace returns a permission error.

Cross-Namespace Access

In some architectures, agents need controlled access to data outside their primary namespaces. HatiData supports this through explicit namespace grants — an organization administrator can grant an agent read-only access to additional namespaces without changing its key scope.

This is useful for analytics agents that need to aggregate data across multiple namespaces, or for supervisor agents that monitor other agents' activities across namespace boundaries.

ABAC Policy Engine

Beyond RBAC (scope-based permissions) and namespace isolation, HatiData includes an Attribute-Based Access Control (ABAC) policy engine for fine-grained authorization. ABAC policies evaluate attributes of the request, the agent, and the data to make authorization decisions.

A policy consists of:

• Conditions — Attribute checks using operators: eq, ne, gt, gte, lt, lte, contains, regex
• Action — What happens when conditions match: block, warn, or log
• Priority — Evaluation order when multiple policies apply

Example policy that prevents agents from accessing PII-tagged columns outside business hours:

{
  "name": "pii-business-hours-only",
  "conditions": [
    {"attribute": "column.tags", "operator": "contains", "value": "pii"},
    {"attribute": "request.time.hour", "operator": "lt", "value": 9},
    {"attribute": "request.time.hour", "operator": "gt", "value": 17}
  ],
  "action": "block",
  "message": "PII columns can only be accessed during business hours (09:00-17:00)"
}

Policies are evaluated in the query pipeline's policy check step, after table extraction and before cost estimation. This means blocked queries never reach the execution engine.

Multi-Tenant Patterns

HatiData supports multi-tenant agent deployments where a single organization runs agents on behalf of multiple customers. The recommended pattern uses a namespace hierarchy:

Organization: acme-ai-services
  |
  +-- Namespace: customer_alpha/support
  +-- Namespace: customer_alpha/analytics
  +-- Namespace: customer_beta/support
  +-- Namespace: customer_beta/analytics
  +-- Namespace: shared/models

Each customer's agents are issued keys with access only to their customer-specific namespaces. A shared namespace can be created for common resources (model configurations, reference data) with read-only grants to all customer agents.

This pattern ensures that Customer Alpha's data is never accessible to Customer Beta's agents, even though they run on the same HatiData infrastructure. The isolation is enforced at the query pipeline level, so it cannot be bypassed.

Audit Trail

Every identity-related operation is recorded in HatiData's audit trail:

• Key creation, rotation, and revocation
• Authentication attempts (successful and failed)
• Namespace access grants and revocations
• Policy violations (blocked queries with the policy that triggered the block)
• Quota threshold warnings and enforcement events

The audit trail is itself protected by the CoT ledger's append-only enforcement — audit records cannot be modified or deleted after creation.

Next Steps

Agent identity is foundational to every other HatiData feature. Keys authenticate MCP tool calls, namespaces isolate memory and reasoning traces, quotas govern resource consumption, and policies enforce fine-grained access rules. See the agent identity documentation for API reference, and the OpenAI agent identity cookbook for a complete multi-agent setup example.