Skip to main content

Permissions and RBAC

Alexandria's permission model has three layers:

  1. Tool ceiling — server-wide cap (server_ceiling)
  2. Group ceiling — per-group cap (ceiling_tools on AgentGroup)
  3. Tenant ceiling — per-tenant cap (applied first in multi-tenant mode)
  4. User allowed tools — what this user may grant
  5. Agent allowed tools — what this specific agent may use

Effective tools = agent ∩ user ∩ server_ceiling ∩ tenant_ceiling.

super_admin bypasses intersection entirely.

Skills​

Skills are reusable capability bundles (system prompt + allowed tools + model hint + tags) that can be attached to agents.

GET /v1/skills​

List all skills. Human access token required.

Response 200 — array of skill objects.

GET /v1/skills/{name}​

Get a skill by name.

POST /admin/skills​

Create a skill. Admin required.

{
  "name": "code-review",
  "version": "1.0.0",
  "description": "Reviews pull requests",
  "system_prompt": "You are an expert code reviewer.",
  "allowed_tools": ["read_file", "post_comment"],
  "model_hint": "claude-3-opus",
  "tags": ["dev", "review"]
}

PATCH /admin/skills/{name}​

Partial update. All fields optional.

DELETE /admin/skills/{name}​

Returns 204.

Groups​

Groups define a tool ceiling that applies to all agents in the group.

GET /v1/groups / GET /v1/groups/{name}​

Read groups. Human access token required.

POST /admin/groups​

{ "name": "security-agents", "description": "High-trust agents" }

DELETE /admin/groups/{name}​

Returns 204.

PUT /admin/groups/{name}/ceiling​

Set the tool ceiling for the group. Wildcards ("*") are rejected — use explicit tool names. Empty list clears the ceiling (unrestricted for the group).

{ "tools": ["web_search", "file_reader"] }

Roles​

Capability roles define named sets of tools that can be assigned to agents, enabling batch tool management.

GET /v1/roles / GET /v1/roles/{name}​

Read roles.

POST /admin/roles​

{
  "name": "code-executor",
  "description": "Can run code in sandboxes",
  "tools": ["python_exec", "bash_exec"]
}

PATCH /admin/roles/{name}​

Update description and/or tools.

DELETE /admin/roles/{name}​

Permission Requests​

Agents can request elevated permissions for a defined time window. Admins approve or reject.

POST /v1/agent/permission-request​

Agent JWT required. Creates a permission request.

Valid request_type values: grant_tool, revoke_tool, create_agent, update_agent, delete_agent, set_ceiling, register_mcp, install_tool, tool_call.

{
  "request_type": "tool_call",
  "requested_scope": { "tool": "execute_code", "session": "s1" },
  "justification": "Need to run analysis script for user request",
  "required_role": "admin",
  "expires_in_secs": 3600
}

Default expiry: 24h. Maximum: 7 days (604800 seconds).

Response 201 — permission request object.

GET /v1/agent/permission-requests​

Agent JWT required. Lists the agent's own permission requests.

Query params

  • status — filter: pending, approved, rejected, expired

GET /admin/permissions​

Admin view of all permission requests.

GET /admin/permissions/{id}​

Get one request.

POST /admin/permissions/{id}/approve​

Approve. Notifies the requesting agent via the notification sink.

POST /admin/permissions/{id}/reject​

{ "reason": "Insufficient justification" }

reason is optional.

Plans​

Plans provide temporary elevated capability grants for agents. Unlike permission requests (which are per-operation), plans activate a temporary agent with a broad grant for a time window.

POST /v1/agent/plan-request​

Agent JWT required. Request a plan.

{
  "justification": "Need file system access for migration task",
  "granted_tools": ["read_file", "write_file", "list_dir"],
  "granted_models": [],
  "granted_skills": [],
  "duration_hours": 2
}

Max duration is configurable via multi_tenancy.max_plan_duration. Returns a PlanRecord.

GET /admin/plans​

List plans. Admin required. Filter by ?status=pending.

GET /admin/plans/{id}​

POST /admin/plans/{id}/approve​

Activates the plan — creates a temporary agent with the granted capabilities.

Response 200

{
  "plan_id": "01HXZ...",
  "temp_agent_id": "plan-tmp-01HXZ...",
  "session_id": "plan-session-01HXZ...",
  "status": "active"
}

POST /admin/plans/{id}/reject​

POST /admin/plans/{id}/complete​

Marks the plan complete and terminates the temporary agent.

curl examples​

# List permission requests (admin)
curl "http://localhost:8080/admin/permissions?status=pending" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq .

# Approve
curl -X POST "http://localhost:8080/admin/permissions/$PR_ID/approve" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq .

# Create group
curl -s -X POST http://localhost:8080/admin/groups \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"security-agents","description":"Restricted agents"}' | jq .

# Set group ceiling
curl -s -X PUT "http://localhost:8080/admin/groups/security-agents/ceiling" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"tools":["web_search"]}' | jq .