Role-Based Access Control (RBAC)

The rbac policy enforces identity requirements and role-based access rules on every request passing through the Keeptrusts gateway. It gates access by requiring specific headers, optionally validating Bearer tokens, mapping users to roles with fine-grained tool permissions, enforcing data-classification ceilings per role, and supporting HIPAA minimum-necessary controls for PHI access.

Use this page when

• You need identity-based access control for your AI gateway (required headers, Bearer token validation, role-based tool permissions).
• You are implementing data classification ceilings per role or HIPAA minimum-necessary PHI access controls.
• You want to restrict which tools each role can invoke and set sensitivity tiers for data access.

Use RBAC when you need to control who can do what through your AI gateway — from simple "every request must identify itself" requirements up to full role-based tool restrictions and data-sensitivity tiers.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Configuration

pack:
  name: rbac-example-1
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
policy:
  rbac:
    deny_if_missing:
    - X-User-ID
    - X-Org-ID
    require_auth: false
    roles:
      admin:
        allowed_tools:
        - "*"
        denied_tools: []
      analyst:
        allowed_tools:
        - search
        - summarize
        denied_tools:
        - execute_code
      viewer:
        allowed_tools:
        - search
        denied_tools: []
    data_access:
      admin:
        max_sensitivity: restricted
      analyst:
        max_sensitivity: confidential
      viewer:
        max_sensitivity: public
    minimum_necessary:
      enabled: false
      allowed_phi_roles:
      - clinician
      - admin

Fields

Top-Level Properties

Property	Type	Default	Description
deny_if_missing	string[]	["X-User-ID"]	List of HTTP headers that must be present on every request. If any listed header is absent, the request is denied immediately with an error. Use this to enforce caller identity before any other policy logic runs.
require_auth	boolean	false	When true, the gateway validates that a Bearer token is present in the Authorization header and that the token is well-formed. Combine with your IdP or API-gateway layer for full JWT validation.
roles	object	{}	A map of role names to role definitions. Each key is a role name (arbitrary string), and each value is an RbacRole object defining that role's tool permissions. Roles are matched against the caller's identity context.
data_access	object	{}	A map of role names to data-access rules. Each key is a role name matching an entry in roles, and each value is an RbacDataAccessRule specifying the maximum data-sensitivity tier the role may access.
minimum_necessary	object	—	HIPAA minimum-necessary enforcement settings. Controls whether the gateway applies the minimum-necessary standard and which roles are permitted to access Protected Health Information (PHI).

roles.<name> — RbacRole

Each entry in the roles map defines a role's tool-access permissions.

Property	Type	Default	Description
allowed_tools	string[]	[]	Tools this role is permitted to invoke. Use "*" as a single entry to allow all tools. An empty list means no tools are allowed unless inherited.
denied_tools	string[]	[]	Tools this role is explicitly denied from invoking. Denied takes precedence over allowed — if a tool appears in both lists, it is denied. Use this for broad-allow-then-narrow-deny patterns (e.g., allowed: ["*"], denied: ["execute_code"]).

data_access.<name> — RbacDataAccessRule

Each entry in the data_access map sets a ceiling on the data-sensitivity tier a role may access.

Property	Type	Default	Allowed Values	Description
max_sensitivity	enum	"public"	"public", "internal", "confidential", "restricted"	The highest data-classification level the role may access. Requests that would expose data above this tier are denied. The hierarchy from least to most sensitive is: public → internal → confidential → restricted.

minimum_necessary — Minimum-Necessary Controls

Property	Type	Default	Description
enabled	boolean	false	When true, the gateway enforces the HIPAA minimum-necessary standard. Requests that access PHI are checked against allowed_phi_roles and denied if the caller's role is not listed.
allowed_phi_roles	string[]	[]	Roles that are permitted to access Protected Health Information. Only meaningful when enabled is true. All other roles are denied PHI access regardless of their data_access tier.

Use Cases

1. Basic Identity Enforcement

Deny any request that does not carry a X-User-ID header — the simplest RBAC setup that ensures every call is attributable to a caller.

pack:
  name: rbac-example-2
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
policy:
  rbac:
    deny_if_missing:
    - X-User-ID

All other RBAC features (roles, data_access, minimum_necessary) are inactive. This is useful as a first step before defining full role structures.

2. Role-Based Tool Access

Grant admins full tool access while restricting viewers to read-only operations. The denied_tools list on the analyst role carves out dangerous capabilities from a broader allow set.

pack:
  name: rbac-example-3
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
policy:
  rbac:
    deny_if_missing:
    - X-User-ID
    - X-User-Role
    roles:
      admin:
        allowed_tools:
        - "*"
        denied_tools: []
      analyst:
        allowed_tools:
        - search
        - summarize
        - export_report
        denied_tools:
        - execute_code
        - delete_record
      viewer:
        allowed_tools:
        - search
        denied_tools: []

3. Data Classification Tiers

Combine role-based tool access with data-sensitivity ceilings. A viewer can only see public data, an analyst can access up to confidential, and only admin can reach restricted data.

pack:
  name: rbac-example-4
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
policy:
  rbac:
    deny_if_missing:
    - X-User-ID
    - X-User-Role
    roles:
      admin:
        allowed_tools:
        - "*"
        denied_tools: []
      analyst:
        allowed_tools:
        - search
        - summarize
        denied_tools: []
      viewer:
        allowed_tools:
        - search
        denied_tools: []
    data_access:
      admin:
        max_sensitivity: restricted
      analyst:
        max_sensitivity: confidential
      viewer:
        max_sensitivity: public

4. HIPAA Minimum-Necessary PHI Access

Enable the minimum-necessary standard so that only explicitly listed roles can access PHI, even if their data_access tier would otherwise allow it.

pack:
  name: rbac-example-5
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
policy:
  rbac:
    deny_if_missing:
    - X-User-ID
    - X-User-Role
    require_auth: true
    roles:
      clinician:
        allowed_tools:
        - patient_lookup
        - lab_results
        - prescribe
        denied_tools: []
      billing:
        allowed_tools:
        - claim_status
        - payment_history
        denied_tools:
        - patient_lookup
      receptionist:
        allowed_tools:
        - schedule
        - search
        denied_tools: []
    data_access:
      clinician:
        max_sensitivity: restricted
      billing:
        max_sensitivity: confidential
      receptionist:
        max_sensitivity: internal
    minimum_necessary:
      enabled: true
      allowed_phi_roles:
      - clinician

In this configuration, only the clinician role can access PHI. The billing role has confidential access but is not in allowed_phi_roles, so PHI-specific requests from billing users are denied.

5. Defense-in-Depth with Agent Firewall

Layer RBAC identity enforcement with the agent-firewall policy for both identity-based and behavioral controls.

pack:
  name: rbac-example-6
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
  - agent-firewall
policy:
  rbac:
    deny_if_missing:
    - X-User-ID
    - X-Org-ID
    require_auth: true
    roles:
      operator:
        allowed_tools:
        - search
        - summarize
        - translate
        denied_tools:
        - execute_code
        - shell
      auditor:
        allowed_tools:
        - search
        - audit_log
        denied_tools: []
    data_access:
      operator:
        max_sensitivity: internal
      auditor:
        max_sensitivity: confidential
  agent-firewall:
    blocked_tools:
    - shell
    - exec
    max_tool_calls_per_turn: 5

RBAC ensures identity is present and roles have correct tool permissions. The agent firewall adds a behavioral ceiling — even if a role somehow gains tool access, the firewall caps invocation counts and blocks dangerous tool names globally.

How It Works

1. Header check: The gateway inspects every incoming request for the headers listed in deny_if_missing. If any are absent, the request is rejected immediately — no further policy evaluation occurs.

2. Auth validation: If require_auth is true, the gateway checks for a valid Bearer token in the Authorization header. Invalid or missing tokens result in denial.

3. Role resolution: The gateway maps the caller's identity (from headers or token claims) to a role defined in the roles map. If no matching role is found, the request is denied or falls through to default-deny behavior.

4. Tool-access evaluation: When the request involves a tool invocation, the gateway checks the resolved role's allowed_tools and denied_tools. Denied takes precedence — a tool in both lists is denied.

5. Data-classification check: If data_access is configured for the resolved role, the gateway evaluates the sensitivity level of the data being accessed. Requests exceeding the role's max_sensitivity ceiling are denied.

6. Minimum-necessary enforcement: When minimum_necessary.enabled is true, requests that access PHI are checked against allowed_phi_roles. Only roles listed there may proceed.

Combining With Other Policies

Policy	Interaction
agent-firewall	RBAC gates by identity and role; agent-firewall gates by behavior (tool call counts, blocked tool names). Use both for defense-in-depth.
pii-detector	RBAC controls who accesses data; PII detector controls what data leaves the system regardless of role.
content-safety	RBAC enforces access rules; content-safety enforces output rules. They operate on different axes and compose cleanly.
audit-log	RBAC decisions (allow/deny) are recorded in the audit log, providing a full trail of who attempted what and whether it was permitted.
rate-limiter	RBAC is per-request identity gating; rate-limiter is per-window throttling. A legitimate user can pass RBAC but still be rate-limited.

Best Practices

• Start with deny_if_missing before configuring roles. Ensure every request is attributable to a caller identity before adding role logic.
• Use denied_tools for carve-outs, not as the primary access control. Define broad allowed_tools and remove specific dangerous capabilities with denied_tools.
• Keep role names consistent across roles, data_access, and minimum_necessary.allowed_phi_roles. Mismatched names silently fail to match.
• Prefer explicit roles over wildcards in production. Reserve "*" allowed-tools for admin roles only.
• Enable require_auth in production to prevent header spoofing. Without auth validation, any caller can set arbitrary identity headers.
• Layer RBAC with behavioral policies (agent-firewall, rate-limiter) for defense-in-depth. RBAC alone does not protect against compromised credentials or token reuse.
• Test role resolution in staging before deploying. Use the gateway's dry-run or audit mode to verify that each identity maps to the expected role and permissions.

For AI systems

• Canonical terms: Keeptrusts, rbac, deny_if_missing, require_auth, roles, allowed_tools, denied_tools, data_access, max_sensitivity, minimum_necessary, allowed_phi_roles
• Config/command names: rbac policy, deny_if_missing, require_auth, roles.<name>.allowed_tools, roles.<name>.denied_tools, data_access.<name>.max_sensitivity, minimum_necessary
• Best next pages: Tool Validation, HIPAA PHI Detector, Routes and Consumer Groups

For engineers

• Prerequisites: Identity headers set by your API gateway or IdP (e.g., X-User-ID, X-Org-ID). For require_auth, a Bearer token validation layer upstream.
• Validation: Send requests without required headers and verify denial. Test role-based tool access by setting the appropriate identity headers. Verify max_sensitivity enforcement by requesting data above the role's ceiling.
• Key commands: kt policy lint, kt gateway run, curl -H 'X-User-ID: test'

For leaders

• Governance: RBAC ensures least-privilege access to AI capabilities. Data classification ceilings prevent sensitive data exposure to unauthorized roles. HIPAA minimum-necessary controls are a regulatory requirement.
• Cost: No external calls — RBAC is evaluated locally from request headers. The governance value (audit trail, access control, compliance evidence) far outweighs the negligible CPU overhead.
• Rollout: Start with deny_if_missing to enforce identity on all requests. Add role definitions incrementally as you map team permissions. Enable minimum_necessary for HIPAA-covered deployments.

Next steps

• Tool Validation — Schema-level tool access control
• HIPAA PHI Detector — PHI-specific access controls
• Routes and Consumer Groups — API key-based access segmentation
• Human Oversight — Escalation for sensitive decisions