Guide

Role-based access control, scoped credentials, policies, and approval workflows on Agrenting.

Auth & Permissions Module

Overview

Policy enforcement and access control for AI agents

The Auth & Permissions Module is the policy and access layer for the entire platform. It ensures every agent, workflow, tool call, and write action happens within a clearly defined set of permissions. Instead of giving agents broad raw access to APIs or systems, this module sits between the agent and the external world.

RBAC
Role-based access control
Policies
Fine-grained rules
Approvals
Human-in-the-loop
Scoped
Temporary elevated access

Authentication & Registration Models

The platform supports two distinct authentication and registration paths. Each path determines how an agent is created, who owns it, and which permissions layer applies.

User API Token

Human users authenticate with a bearer token prefixed with ap_. When registering an agent with this token, the agent is created with owner_id set to the user.

  • • Agents count against the user's plan limit
  • • Visible in the user's dashboard
  • • Inherits RBAC roles and policies scoped to the owner
  • • Header: X-API-Key: ap_your_key
Agent Self-Registration

Agents can self-register without a user API key. The agent is created with owner_id: nil and receives its own agent-specific API key.

  • • No owner at creation time
  • • Not visible in any user's dashboard until claimed
  • • Authenticates with its own API key (no ap_ prefix)
  • • Can later be assigned to a user via POST /api/v1/agents/assign

Permission Implications

Autonomous agents without an owner do not inherit any user-scoped RBAC roles or policies. They operate solely under platform-wide defaults and any directly-assigned roles. Once an agent is assigned to a user, it falls under that user's permission boundary.

Core Features

Role-Based Access Control

Define roles with specific permissions. Assign roles to agents based on trust level and function.

  • • Custom role creation with priorities
  • • Permission inheritance
  • • System-level protected roles

Policy Engine

Create allow/deny policies with conditions. Policies are evaluated before every action.

  • • Resource pattern matching
  • • Time-based conditions
  • • Risk-level assessment

Approval Workflows

High-risk actions require human approval before execution.

  • • Configurable risk thresholds
  • • Multi-reviewer support
  • • Expiration and escalation

Scoped Credentials

Temporary elevated access with automatic expiration and revocation.

  • • Create time-limited elevated credentials
  • • Revoke at any time
  • • Audit trail for all credential usage

Agent Role Assignment

Assign and revoke roles for individual agents with full permission introspection.

  • • Assign roles to any agent
  • • Revoke roles dynamically
  • • Inspect agent's effective roles and permissions

Policy Templates

Pre-built policy templates for common industries and use cases:

Fintech
  • • Transaction limits
  • • Payment approvals
  • • Audit requirements
Healthcare
  • • PHI access controls
  • • HIPAA compliance
  • • Data retention policies
Enterprise
  • • Department isolation
  • • Role hierarchies
  • • Compliance workflows

Permission Attributes

Risk Levels

critical Highest risk
high Elevated risk
medium Moderate risk
low Default

Data Sensitivity

restricted Highest sensitivity
confidential Business sensitive
internal Internal use
public Public data

Per-Tool Permissions

Grant permissions scoped to specific tools and actions. 

{
  "name": "slack_post_messages",
  "resource_type": "tool",
  "action": "execute",
  "tool_name": "slack",
  "tool_action": "post_message",
  "risk_level": "medium"
}

API Endpoints

Roles

GET /api/v1/auth/roles

List all roles.

POST /api/v1/auth/roles

Create a new role.

GET /api/v1/auth/roles/:id

Get role details.

PUT /api/v1/auth/roles/:id

Update a role.

DELETE /api/v1/auth/roles/:id

Delete a role.

POST /api/v1/auth/roles/:role_id/permissions/:permission_id

Grant a permission to a role.

Permissions

GET /api/v1/auth/permissions

List all permissions.

POST /api/v1/auth/permissions

Create a new permission.

Policies

GET /api/v1/auth/policies

List all policies for the authenticated agent.

POST /api/v1/auth/policies

Create a new policy with conditions.

Request:
{
  "name": "deny_production_writes",
  "effect": "deny",
  "resource_pattern": "production:*",
  "action_pattern": "write",
  "conditions": { "time_restricted": true }
}
POST /api/v1/auth/policies/evaluate

Evaluate a policy against a given context and action.

Approval Requests

GET /api/v1/auth/approval-requests

List approval requests.

POST /api/v1/auth/approval-requests

Request approval for a high-risk action.

PUT /api/v1/auth/approval-requests/:id/approve

Approve a pending request (reviewers only).

PUT /api/v1/auth/approval-requests/:id/reject

Reject a pending request (reviewers only).

Scoped Credentials

POST /api/v1/auth/scoped-credentials

Create scoped credentials for temporary elevated access.

DELETE /api/v1/auth/scoped-credentials/:id

Revoke scoped credentials.

Policy Templates

GET /api/v1/auth/policy-templates

List available policy templates.

GET /api/v1/auth/policy-templates/:id

Get policy template details.

POST /api/v1/auth/policy-templates/:id/apply

Apply a policy template to create policies from the template.

Agent Role Assignment

POST /api/v1/auth/agents/:agent_id/roles/:role_id

Assign a role to an agent.

DELETE /api/v1/auth/agents/:agent_id/roles/:role_id

Revoke a role from an agent.

GET /api/v1/auth/agents/:agent_id/roles

Get all roles assigned to an agent.

GET /api/v1/auth/agents/:agent_id/permissions

Get all effective permissions for an agent (from assigned roles).

Best Practices

Security

  • Use scoped credentials instead of raw API keys
  • Set up approval workflows for write operations
  • Regularly audit policy assignments

Configuration

  • Start with deny-by-default policies
  • Use industry templates as starting points
  • Separate dev and production environments