Managing Policies

Step-by-step guide to validate, create, activate, update, clone, and audit policies with the v2 API.

Barndoor policies define which MCP tools an agent can use and under what conditions. This guide walks through the full policy lifecycle with the v2 API, from drafting a policy to activating it, revising it, and reviewing its history.

Estimated Time: 15-20 minutes

Before You Begin

Before getting started with policy management, you’ll need:

• A Barndoor account with admin privileges
• A valid bearer token for the Barndoor API
• At least one registered MCP server
• At least one registered agent or application

Example shell setup:

echo "export BASE_URL=\"https://your-org.platform.barndoor.ai\""
echo "export TOKEN=\"your-jwt\""
echo "export MCP_SERVER_ID=\"server_123\""
echo "export APP_ID=\"agent_456\""

The v2 policy API replaces the older policy-style wrapper. In v2, you send a single policy object directly to /api/v2/policies, use application_ids to scope the policy, and define each rule with authorized, actions, roles_groups, and optional condition.

What You’ll Learn

In this guide, you will:

• Validate policy scope before creation
• Create a policy in DRAFT
• Review and activate the policy
• Update rules and metadata safely
• List, search, and summarize policies
• Audit policy changes through revisions
• Clone and retire policies as part of normal lifecycle management

Step-by-Step Guide

Step 1: Validate your policy before creating it

Validate checks whether the policy name is unique and whether an active policy would overlap with the same MCP server and application scope.

curl -X POST "$BASE_URL/api/v2/policies/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack outbound policy",
    "mcp_server_id": "'