Create Policy
curl --request POST \
--url https://{host}/api/policy/v2/policies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"name": "<string>",
"mcp_server_id": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": [
"<string>"
],
"application_ids": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
EOFimport requests
url = "https://{host}/api/policy/v2/policies"
payload = {
"name": "<string>",
"mcp_server_id": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": ["<string>"],
"application_ids": ["<string>"],
"rules": [
{
"actions": ["tools/call:create_issue"],
"name": "Engineering read access",
"description": "<string>",
"authorized": False,
"active": True,
"roles_groups": ["*"],
"condition": { "match": { "expr": "P.attr.department == 'Engineering'" } }
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
mcp_server_id: '<string>',
description: '<string>',
support_contact: '<string>',
tags: ['<string>'],
application_ids: ['<string>'],
rules: [
{
actions: ['tools/call:create_issue'],
name: 'Engineering read access',
description: '<string>',
authorized: false,
active: true,
roles_groups: ['*'],
condition: {match: {expr: 'P.attr.department == \'Engineering\''}}
}
]
})
};
fetch('https://{host}/api/policy/v2/policies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/policy/v2/policies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'mcp_server_id' => '<string>',
'description' => '<string>',
'support_contact' => '<string>',
'tags' => [
'<string>'
],
'application_ids' => [
'<string>'
],
'rules' => [
[
'actions' => [
'tools/call:create_issue'
],
'name' => 'Engineering read access',
'description' => '<string>',
'authorized' => false,
'active' => true,
'roles_groups' => [
'*'
],
'condition' => [
'match' => [
'expr' => 'P.attr.department == \'Engineering\''
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/api/policy/v2/policies"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"mcp_server_id\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{host}/api/policy/v2/policies")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"mcp_server_id\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/policy/v2/policies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"mcp_server_id\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"policy": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "<string>",
"name": "<string>",
"status": "<string>",
"mcp_server_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"created_by_user_id": "<string>",
"updated_by_user_id": "<string>",
"support_contact": "<string>",
"description": "<string>",
"application_ids": [
"<string>"
],
"tags": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Policies
Create Policy
Create a policy governing exactly one MCP server.
A rule grants its `actions` to its `roles_groups`. Access is denied by default, so a
tool no rule grants is already blocked — `authorized: false` is only for carving an
exception out of a broader allow.
Write ONE rule per `roles_groups` set — all of a principal's actions on one rule,
with `:approve` carrying allow-vs-confirm. Example, reads free and writes confirmed:
{"name": "Support tooling", "mcp_server_id": "3f7c…", "rules": [
{"name": "Support issue access", "authorized": true, "active": true,
"actions": ["tools/call:list_issues", "tools/call:create_issue:approve"],
"roles_groups": ["group:Support"]}]}
One policy per (server, agent scope): a second ACTIVE policy over the same
`mcp_server_id` and `application_ids` is refused with 409 naming the holder. Add rules
to the existing policy instead, or scope the new one to specific `application_ids`.
`validate_policy` reports this before you write.
POST
/
api
/
policy
/
v2
/
policies
Create Policy
curl --request POST \
--url https://{host}/api/policy/v2/policies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"name": "<string>",
"mcp_server_id": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": [
"<string>"
],
"application_ids": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
EOFimport requests
url = "https://{host}/api/policy/v2/policies"
payload = {
"name": "<string>",
"mcp_server_id": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": ["<string>"],
"application_ids": ["<string>"],
"rules": [
{
"actions": ["tools/call:create_issue"],
"name": "Engineering read access",
"description": "<string>",
"authorized": False,
"active": True,
"roles_groups": ["*"],
"condition": { "match": { "expr": "P.attr.department == 'Engineering'" } }
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
mcp_server_id: '<string>',
description: '<string>',
support_contact: '<string>',
tags: ['<string>'],
application_ids: ['<string>'],
rules: [
{
actions: ['tools/call:create_issue'],
name: 'Engineering read access',
description: '<string>',
authorized: false,
active: true,
roles_groups: ['*'],
condition: {match: {expr: 'P.attr.department == \'Engineering\''}}
}
]
})
};
fetch('https://{host}/api/policy/v2/policies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/policy/v2/policies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'mcp_server_id' => '<string>',
'description' => '<string>',
'support_contact' => '<string>',
'tags' => [
'<string>'
],
'application_ids' => [
'<string>'
],
'rules' => [
[
'actions' => [
'tools/call:create_issue'
],
'name' => 'Engineering read access',
'description' => '<string>',
'authorized' => false,
'active' => true,
'roles_groups' => [
'*'
],
'condition' => [
'match' => [
'expr' => 'P.attr.department == \'Engineering\''
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/api/policy/v2/policies"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"mcp_server_id\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{host}/api/policy/v2/policies")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"mcp_server_id\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/policy/v2/policies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"mcp_server_id\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"policy": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "<string>",
"name": "<string>",
"status": "<string>",
"mcp_server_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"created_by_user_id": "<string>",
"updated_by_user_id": "<string>",
"support_contact": "<string>",
"description": "<string>",
"application_ids": [
"<string>"
],
"tags": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
ApiKeyOAuth2
A Barndoor API key, sent as Authorization: Bearer <key>. Keys are prefixed bdai_ and are opaque — do not attempt to decode one. Interchangeable with an OAuth 2.0 access token.
Body
application/json
Request body for creating a new policy.
Human-friendly policy name, unique within an organization. Required when creating.
UUID of the MCP server this policy governs. Immutable after creation — rules reference server-specific tool actions, so target a different server by creating a new policy rather than editing this one. Retrieve real ids from GET /api/registry/v1/servers.
Longer description of the policy.
Primary point of contact associated with the policy.
Tags for categorizing the policy.
The current lifecycle status of the policy.
Available options:
DRAFT, ACTIVE, INACTIVE, ARCHIVED AI agents this policy applies to, as application UUIDs. An empty or omitted list means the policy applies to ALL agents — it must never contain an empty string. Retrieve real ids from GET /api/registry/v1/agents.
Full set of rules that govern the policy. This REPLACES the existing rule list on update — send the complete set, not a delta. Anything no rule grants is denied. Write ONE rule per distinct roles_groups set: put every action for a principal on a single rule and let the :approve suffix carry allow-vs-confirm, rather than splitting reads and writes across two rules naming the same principal.
Show child attributes
Show child attributes
Response
Successful Response
Envelope for detail responses.
Detailed representation of a policy including rules.
Show child attributes
Show child attributes