Capability Requests

Capability Requests enable a secure approval workflow for agents requiring additional permissions. Administrators can review and approve/reject capability requests through the admin dashboard or API. This ensures zero-trust security while enabling agents to adapt to new requirements.

📝 API Examples Note: The API examples on this page use https://api.opena2a.org for demonstration. Replace this with your AIM server URL (e.g., http://localhost:8080 for local deployment).

Security First: All capability expansions require explicit admin approval. Agents cannot self-grant capabilities, ensuring compliance and security.

Request Workflow

1. Review

Admin reviews pending capability requests and decides to approve or reject.

under review

2. Decision

Request is approved or rejected with reason.

approvedrejected

Request Status Types

pendingRequest submitted and awaiting admin review
approvedRequest approved - capability granted to agent
rejectedRequest rejected - capability not granted

Admin: List Capability Requests

Administrators can view all capability requests across the organization. Filter by status to see only pending, approved, or rejected requests.

GET /v1/admin/capability-requests

curl -X GET "https://api.opena2a.org/v1/admin/capability-requests?status=pending&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

Response (200 OK)

{
  "requests": [
    {
      "id": "req_9mK3n5pL8qR7sT2u",
      "agent_id": "agent_2KL9m3nX8fY5pQr7",
      "agent_name": "customer-support-agent",
      "capability_name": "db:write",
      "resource": "users_table",
      "justification": "Agent needs to update user profile information based on customer feedback analysis",
      "constraints": {
        "max_records_per_hour": 500,
        "allowed_operations": ["UPDATE"],
        "excluded_columns": ["password", "ssn", "credit_card"]
      },
      "status": "pending",
      "requested_at": "2024-01-15T10:30:00Z",
      "requested_by": "user_4kL2m6nX9pQ5rS8t",
      "reviewed_at": null,
      "reviewed_by": null,
      "review_notes": null
    },
    {
      "id": "req_8jJ2m4nY7pK6qS3v",
      "agent_id": "agent_5mN8p2qL9rX3sU6w",
      "agent_name": "analytics-agent",
      "capability_name": "api:call",
      "resource": "analytics.external.com",
      "justification": "Need to fetch real-time market data for analytics dashboard",
      "constraints": {
        "allowed_domains": ["analytics.external.com", "api.analytics.com"],
        "rate_limit_per_minute": 60
      },
      "status": "pending",
      "requested_at": "2024-01-15T09:15:00Z",
      "requested_by": "user_6nO3p7qM2rY9sV4x",
      "reviewed_at": null,
      "reviewed_by": null,
      "review_notes": null
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Admin: Get Specific Request

Retrieve detailed information about a specific capability request by ID.

GET /v1/admin/capability-requests/:id

curl -X GET https://api.opena2a.org/v1/admin/capability-requests/req_9mK3n5pL8qR7sT2u \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

Response (200 OK)

{
  "id": "req_9mK3n5pL8qR7sT2u",
  "agent_id": "agent_2KL9m3nX8fY5pQr7",
  "agent_name": "customer-support-agent",
  "capability_name": "db:write",
  "resource": "users_table",
  "justification": "Agent needs to update user profile information based on customer feedback analysis",
  "constraints": {
    "max_records_per_hour": 500,
    "allowed_operations": ["UPDATE"],
    "excluded_columns": ["password", "ssn", "credit_card"]
  },
  "status": "pending",
  "requested_at": "2024-01-15T10:30:00Z",
  "requested_by": "user_4kL2m6nX9pQ5rS8t",
  "requester": {
    "id": "user_4kL2m6nX9pQ5rS8t",
    "email": "john.doe@company.com",
    "full_name": "John Doe"
  },
  "reviewed_at": null,
  "reviewed_by": null,
  "review_notes": null
}

Admin: Approve Request

Approve a capability request and grant the capability to the agent. Optionally modify the constraints before approval.

POST /v1/admin/capability-requests/:id/approve

curl -X POST https://api.opena2a.org/v1/admin/capability-requests/req_9mK3n5pL8qR7sT2u/approve \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "review_notes": "Approved for profile updates only. Monitor usage closely.",
    "constraints": {
      "max_records_per_hour": 300,
      "allowed_operations": ["UPDATE"],
      "excluded_columns": ["password", "ssn", "credit_card", "email"]
    },
    "expires_at": "2024-06-30T23:59:59Z"
  }'

Response (200 OK)

{
  "id": "req_9mK3n5pL8qR7sT2u",
  "agent_id": "agent_2KL9m3nX8fY5pQr7",
  "capability_name": "db:write",
  "resource": "users_table",
  "status": "approved",
  "requested_at": "2024-01-15T10:30:00Z",
  "requested_by": "user_4kL2m6nX9pQ5rS8t",
  "reviewed_at": "2024-01-15T11:45:00Z",
  "reviewed_by": "admin_7pQ4r2sM9uX6vY3z",
  "review_notes": "Approved for profile updates only. Monitor usage closely.",
  "granted_capability": {
    "id": "cap_3nL5m8pR6qT9sU2v",
    "capability": "db:write",
    "resource": "users_table",
    "constraints": {
      "max_records_per_hour": 300,
      "allowed_operations": ["UPDATE"],
      "excluded_columns": ["password", "ssn", "credit_card", "email"]
    },
    "granted_at": "2024-01-15T11:45:00Z",
    "expires_at": "2024-06-30T23:59:59Z"
  }
}

Admin: Reject Request

Reject a capability request with a reason. The agent will not receive the requested capability.

POST /v1/admin/capability-requests/:id/reject

curl -X POST https://api.opena2a.org/v1/admin/capability-requests/req_8jJ2m4nY7pK6qS3v/reject \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "review_notes": "Rejected: External API access requires security audit. Please submit audit report first."
  }'

Response (200 OK)

{
  "id": "req_8jJ2m4nY7pK6qS3v",
  "agent_id": "agent_5mN8p2qL9rX3sU6w",
  "capability_name": "api:call",
  "resource": "analytics.external.com",
  "status": "rejected",
  "requested_at": "2024-01-15T09:15:00Z",
  "requested_by": "user_6nO3p7qM2rY9sV4x",
  "reviewed_at": "2024-01-15T11:50:00Z",
  "reviewed_by": "admin_7pQ4r2sM9uX6vY3z",
  "review_notes": "Rejected: External API access requires security audit. Please submit audit report first."
}

Request Lifecycle

Complete Lifecycle

Review: Admin evaluates capability requests, justifications, and constraints
Decision: Admin approves (grants capability) or rejects (no capability granted)
Notification: Requester is notified of approval/rejection
Audit: Full audit trail recorded for compliance

Best Practices

Security

• Require detailed justification for all requests
• Review and modify constraints before approval
• Set expiration dates for temporary capabilities
• Monitor capability usage after granting
• Revoke capabilities if misused

Efficiency

• Review requests daily to avoid blocking agents
• Use clear rejection reasons for resubmission
• Document approval criteria for consistency
• Batch approve similar requests when appropriate
• Set up webhooks for automated notifications

Documentation

• Provide clear justification in requests
• Include use cases and expected outcomes
• Document risk mitigation strategies
• Add review notes for future reference
• Maintain audit trail for compliance

Compliance

• All requests require admin approval
• Full audit trail automatically recorded
• Compliance reports include all requests
• Regular access reviews include capabilities
• SOC 2, HIPAA, GDPR compliance built-in

Query Parameters

Parameter	Type	Description
status	string	Filter by status: `pending`, `approved`, `rejected`
agent_id	string	Filter by specific agent ID
capability_name	string	Filter by capability type
limit	integer	Number of results to return (default: 50, max: 100)
offset	integer	Number of results to skip for pagination

Available Endpoints

Method	Endpoint	Access	Description
GET	/admin/capability-requests	Admin	List all capability requests
GET	/admin/capability-requests/:id	Admin	Get specific request details
POST	/admin/capability-requests/:id/approve	Admin	Approve request and grant capability
POST	/admin/capability-requests/:id/reject	Admin	Reject request with reason

Important Security Note

All capability requests require explicit admin approval. Agents cannot self-grant capabilities. This ensures zero-trust security and compliance with your security policies.

Capability Requests

Request Workflow

1. Review

2. Decision

Request Status Types

Admin: List Capability Requests

Admin: Get Specific Request

Admin: Approve Request

Admin: Reject Request

Request Lifecycle

Complete Lifecycle

Best Practices

Security

Efficiency

Documentation

Compliance

Query Parameters

Available Endpoints

Next Steps

Agent Management

User Management

Trust Scoring

REST API Reference