Managing Policies - Barndoor Documentation

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:

export BASE_URL="https://your-org.platform.barndoor.ai"
export TOKEN="your-jwt"
export MCP_SERVER_ID="server_123"
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
Grant a tool outright or subject to user approval
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.

Show Validation request example

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": "'"$MCP_SERVER_ID"'",
    "application_ids": ["'"$APP_ID"'"]
  }'

Typical response:

{
  "name_is_unique": true,
  "no_overlap_if_active": true,
  "overlapping_policy_names": []
}

Use exclude_policy_id when validating an update to an existing policy so the current record is ignored during overlap checks.

Reference: POST /api/v2/policies/validate

Step 2: Create the policy as a draft

In v2, the request body is a single policy object. There is no resourcePolicy wrapper.

Show Draft policy payload example

curl -X POST "$BASE_URL/api/v2/policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack outbound policy",
    "description": "Default outbound Slack controls for the support agent.",
    "support_contact": "[email protected]",
    "tags": ["slack", "support"],
    "status": "DRAFT",
    "mcp_server_id": "'"$MCP_SERVER_ID"'",
    "application_ids": ["'"$APP_ID"'"],
    "rules": [
      {
        "name": "allow_all",
        "authorized": true,
        "actions": ["*"],
        "roles_groups": ["*"]
      },
      {
        "name": "block_general_channel",
        "authorized": false,
        "actions": ["tools/call:chat_postMessage"],
        "roles_groups": ["*"],
        "condition": {
          "match": {
            "all": {
              "of": [
                {
                  "expr": "request.resource.attr.channel == \"general\""
                }
              ]
            }
          }
        }
      }
    ]
  }'

Important v2 fields:

name: Unique policy name within the organization
mcp_server_id: MCP server this policy controls
application_ids: Agents or applications this policy applies to
status: DRAFT, ACTIVE, INACTIVE, or ARCHIVED
rules: Array of policy rules

Reference: POST /api/v2/policies

Step 3: Understand the v2 rule model

Each rule in v2 uses a simpler structure than the older effect-based format.

Show Rule model details

authorized: true means allow
authorized: false means deny
actions defines which MCP actions the rule applies to
roles_groups controls which role or group matchers apply
condition adds optional fine-grained logic

Use roles_groups: ["*"] when a rule should apply to every user. To target a specific IdP group, use the exact group name that Barndoor receives from your IdP, for example roles_groups: ["Finance"].

Group-based policy rules only work after your IdP sends group membership to Barndoor during login. For OIDC IdPs, configure a groups claim in the ID token or UserInfo response and verify users have signed in again after the claim was added.

Single-expression condition:

{
  "condition": {
    "match": {
      "expr": "request.resource.attr.channel == \"general\""
    }
  }
}

Nested condition with all:

{
  "condition": {
    "match": {
      "all": {
        "of": [
          { "expr": "request.resource.attr.channel == \"general\"" },
          { "expr": "request.principal.id == \"agent_456\"" }
        ]
      }
    }
  }
}

Step 4: Require approval for a tool

A rule can grant a tool outright or grant it subject to user approval. The difference is carried in the action string: append :approve to the tool call. This is the API-level view of the same three states the portal exposes per tool — see Granular Tool Use Confirmations for the UI walkthrough and the enforcement caveats.

Intent	Action string
Always Allow — runs without confirmation	`tools/call:create_issue`
Needs Approval — user confirms before it runs	`tools/call:create_issue:approve`
Off — not granted	omit the tool from the rule

Use one form per tool per rule, never both. :approve is the whole grant — a tool listed as tools/call:create_issue:approve is granted, with an approval gate attached. Listing the plain action alongside it makes the approval gate moot, because the plain grant already permits the call unconfirmed.

The tri-state has no explicit deny form. “Off” is absence — a tool that no applicable rule grants is denied because nothing granted it, so turning a tool off means removing it from the rule rather than adding a rule against it. That is different from an authorized: false rule (Step 3), which serializes to a real deny and overrides any allow that would otherwise apply. Use authorized: false with a condition to carve a specific exception out of a grant; use omission to express “this group does not get this tool”.

Show Rule with mixed always-allow and needs-approval tools

curl -X POST "$BASE_URL/api/v2/policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jira support policy",
    "description": "Reads run freely; writes need a human.",
    "status": "DRAFT",
    "mcp_server_id": "'"$MCP_SERVER_ID"'",
    "application_ids": ["'"$APP_ID"'"],
    "rules": [
      {
        "name": "support_engineers",
        "authorized": true,
        "actions": [
          "tools/call:search_issues",
          "tools/call:get_issue",
          "tools/call:create_issue:approve",
          "tools/call:update_issue:approve"
        ],
        "roles_groups": ["Support"]
      }
    ]
  }'

search_issues and get_issue run immediately. create_issue and update_issue return an approval request to the user first. delete_issue is absent, so the Support group cannot call it at all.

The :approve suffix is reserved. It may appear at most once, at the end of a tool-call action — the API rejects a doubled tools/call:X:approve:approve.

How overlapping grants resolve

A user is usually in more than one group, and rules are evaluated together rather than in order. The most permissive grant wins, regardless of the order rules appear in:

Always Allow  >  Needs Approval  >  Off

This makes a broad grant capable of silencing a narrow one. If an unscoped rule (roles_groups: ["*"]) grants tools/call:create_issue plainly, then a group-scoped rule granting tools/call:create_issue:approve is dormant — those users are already allowed unconfirmed, so no approval fires. The narrower rule is not broken and does not need rewriting: remove or downgrade the broad grant and the approval requirement takes effect. Read the whole rule set, not just the rule you are editing, before concluding a tool is gated.

The same resolution is what the app’s policy detail view renders, so the UI and the API agree about a given tool’s effective state.

Approval prompting happens through Barndoor’s tool router only. On the direct MCP path, a tool granted tools/call:X:approve is permitted and executes with no prompt — the approval ceremony lives in the tool router, not in the proxy. Treat :approve as a control for tool-router traffic; for a hard stop on every path, omit the tool instead.

Step 5: Review the created policy

Capture the returned policy.id from the create response, then fetch the full policy document.

Show Fetch a policy by ID

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v2/policies/POLICY_ID"

Confirm the following before rollout:

The status is still DRAFT
The correct application_ids are attached
The mcp_server_id is correct
The returned rules match your intended behavior

Reference: GET /api/v2/policies/{policy_id}

Step 6: Activate or update the policy

Once reviewed, move the policy into ACTIVE.

Show Activation and update examples

curl -X PATCH "$BASE_URL/api/v2/policies/POLICY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACTIVE"
  }'

You can also update metadata and rules through the same endpoint:

curl -X PATCH "$BASE_URL/api/v2/policies/POLICY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Blocks posting to #general while allowing all other Slack tools.",
    "tags": ["slack", "support", "production"],
    "rules": [
      {
        "name": "allow_all",
        "authorized": true,
        "actions": ["*"],
        "roles_groups": ["*"]
      },
      {
        "name": "block_general_channel",
        "authorized": false,
        "actions": ["tools/call:chat_postMessage"],
        "roles_groups": ["*"],
        "condition": {
          "match": {
            "all": {
              "of": [
                {
                  "expr": "request.resource.attr.channel == \"general\""
                }
              ]
            }
          }
        }
      }
    ]
  }'

Reference: PATCH /api/v2/policies/{policy_id}

Step 7: List, search, and summarize policies

List policies:

Show List and search examples

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v2/policies?page=1&limit=20"

Search and filter:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v2/policies?search=slack&status=ACTIVE&mcp_server_id=$MCP_SERVER_ID&agent_id=$APP_ID"

Get status counts:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v2/policies/summary"

Get filter definitions for a UI:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v2/policies/filter-definitions"

References:

Step 8: Review revision history

Every meaningful change is available through the revisions endpoint.

Show Revision history example

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v2/policies/POLICY_ID/revisions?changes_summary=true&page=1&limit=10"

Use revisions to:

Review what changed
See who changed it
Understand when the policy moved between lifecycle states

Reference: GET /api/v2/policies/{policy_id}/revisions

Step 9: Clone, deactivate, or archive a policy

Clone a policy to create a safe variation without rebuilding the rule set:

Show Clone and retirement examples

curl -X POST "$BASE_URL/api/v2/policies/POLICY_ID/clone" \
  -H "Authorization: Bearer $TOKEN"

The cloned policy should be reviewed and edited before activation.To retire a policy gradually, move it to INACTIVE:

curl -X PATCH "$BASE_URL/api/v2/policies/POLICY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INACTIVE"
  }'

To remove it from normal circulation, move it to ARCHIVED:

curl -X PATCH "$BASE_URL/api/v2/policies/POLICY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "ARCHIVED"
  }'

References:

Legacy Endpoints

The older engine-level toggles still exist:

Show Legacy endpoint references

For new policy lifecycle workflows, prefer the v2 endpoints and the status field. Use the legacy endpoints only when you explicitly need the older engine-level toggles.

Best Practices

Create policies as DRAFT first, then promote to ACTIVE
Validate before both create and update operations
Keep application_ids narrow to avoid overlap with other active policies
Before relying on a :approve grant, check that no broader rule grants the same tool plainly — the plain grant wins and the approval never fires
Use descriptive tags and a support_contact so ownership is clear
Review revisions instead of maintaining a separate manual change log
Clone stable policies before making large behavior changes

​Before You Begin

​What You’ll Learn

​Step-by-Step Guide

​Step 1: Validate your policy before creating it

​Step 2: Create the policy as a draft

​Step 3: Understand the v2 rule model

​Step 4: Require approval for a tool

​How overlapping grants resolve

​Step 5: Review the created policy

​Step 6: Activate or update the policy

​Step 7: List, search, and summarize policies

​Step 8: Review revision history

​Step 9: Clone, deactivate, or archive a policy

​Legacy Endpoints

​Best Practices

Before You Begin

What You’ll Learn

Step-by-Step Guide

Step 1: Validate your policy before creating it

Step 2: Create the policy as a draft

Step 3: Understand the v2 rule model

Step 4: Require approval for a tool

How overlapping grants resolve

Step 5: Review the created policy

Step 6: Activate or update the policy

Step 7: List, search, and summarize policies

Step 8: Review revision history

Step 9: Clone, deactivate, or archive a policy

Legacy Endpoints

Best Practices