Skip to main content
Policies control network access between groups of peers by defining rules that specify which peers can communicate, on which protocols and ports.

​
List All Policies

Returns a list of all access control policies. 
GET /api/policies

curl -X GET https://api.netbird.io/api/policies \
  -H "Authorization: Token nbp_YOUR_TOKEN"
​
id
string
Unique policy identifier
​
name
string
Policy name
​
description
string
Policy description
​
enabled
boolean
Whether the policy is active
​
source_posture_checks
array
Posture check IDs applied to source groups
​
rules
array
List of policy rules defining access controls

​
Get a Policy

Retrieve detailed information about a specific policy. 
GET /api/policies/{policyId}
​
policyId
string
required
The unique identifier of the policy
Example
curl -X GET https://api.netbird.io/api/policies/ch8i4ug6lnn4g9hqv7mg \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Create a Policy

Create a new access control policy with rules. 
POST /api/policies
​
name
string
required
Policy name
​
description
string
Policy description
​
enabled
boolean
required
Whether the policy is active
​
source_posture_checks
array
Posture check IDs to apply to source groups
​
rules
array
required
List of policy rules
curl -X POST https://api.netbird.io/api/policies \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Allow SSH Access",
    "description": "Allow admins to SSH into servers",
    "enabled": true,
    "source_posture_checks": [],
    "rules": [
      {
        "name": "SSH Rule",
        "description": "SSH access on port 22",
        "enabled": true,
        "action": "accept",
        "bidirectional": false,
        "protocol": "tcp",
        "ports": ["22"],
        "sources": ["ch8i4ug6lnn4g9hqv797"],
        "destinations": ["ch8i4ug6lnn4g9h7v7m0"]
      }
    ]
  }'

​
Update a Policy

Update an existing policy and its rules. 
PUT /api/policies/{policyId}
​
policyId
string
required
The unique identifier of the policy
​
name
string
required
Policy name
​
enabled
boolean
required
Whether the policy is active
​
rules
array
required
Complete list of policy rules (replaces existing rules)
Example
curl -X PUT https://api.netbird.io/api/policies/ch8i4ug6lnn4g9hqv7mg \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Policy Name",
    "enabled": true,
    "source_posture_checks": ["chacdk86lnnboviihd70"],
    "rules": [...]
  }'

​
Delete a Policy

Remove a policy from the network. 
DELETE /api/policies/{policyId}
​
policyId
string
required
The unique identifier of the policy
Example
curl -X DELETE https://api.netbird.io/api/policies/ch8i4ug6lnn4g9hqv7mg \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Policy Rules

Each policy contains one or more rules that define access controls.

​
Rule Fields

​
name
string
required
Rule name
​
description
string
Rule description
​
enabled
boolean
required
Whether the rule is active
​
action
string
required
Action to take: accept or drop
​
bidirectional
boolean
required
Whether the rule applies in both directions
​
protocol
string
required
Protocol type: all, tcp, udp, icmp, or netbird-ssh
​
ports
array
List of port numbers (for TCP/UDP)
​
port_ranges
array
List of port range objects with start and end fields
​
sources
array
required
Source group IDs
​
destinations
array
required
Destination group IDs
​
sourceResource
object
Source resource object (alternative to sources)
​
destinationResource
object
Destination resource object (alternative to destinations)

​
Protocol Examples

{
  "protocol": "tcp",
  "ports": ["443", "8080"]
}

​
Policy Actions

Accept

Allow traffic matching the rule

Drop

Block traffic matching the rule

​
Bidirectional Rules

When bidirectional: true, the rule applies in both directions: 
{
  "bidirectional": true,
  "sources": ["group-a"],
  "destinations": ["group-b"]
}
This allows:
  • Group A → Group B
  • Group B → Group A

​
Posture Checks

Apply security requirements to source groups: 
{
  "source_posture_checks": [
    "chacdk86lnnboviihd70"
  ]
}
Peers in source groups must pass all specified posture checks before the policy applies.

​
Common Policy Patterns

​
Allow All Within Group

{
  "name": "Internal Team Access",
  "enabled": true,
  "rules": [
    {
      "name": "All Traffic",
      "action": "accept",
      "bidirectional": true,
      "protocol": "all",
      "sources": ["team-group-id"],
      "destinations": ["team-group-id"]
    }
  ]
}

​
Database Access

{
  "name": "Database Access",
  "enabled": true,
  "rules": [
    {
      "name": "PostgreSQL",
      "action": "accept",
      "bidirectional": false,
      "protocol": "tcp",
      "ports": ["5432"],
      "sources": ["app-servers-group"],
      "destinations": ["database-group"]
    }
  ]
}

​
Zero Trust Access

{
  "name": "Production Access",
  "enabled": true,
  "source_posture_checks": [
    "os-version-check",
    "antivirus-check"
  ],
  "rules": [
    {
      "name": "SSH Access",
      "action": "accept",
      "protocol": "tcp",
      "ports": ["22"],
      "sources": ["admins-group"],
      "destinations": ["production-group"]
    }
  ]
}

​
Best Practices

Start with deny-all - Create policies that explicitly allow only required traffic
Use specific protocols and ports - Avoid using "protocol": "all" when possible
Enable posture checks - Require security compliance for sensitive access
Document policies - Add clear descriptions explaining the purpose of each policy
Test before deploying - Verify policies in a test environment first
Review regularly - Audit policies periodically to ensure they’re still needed

Build docs developers (and LLMs) love

Get started for freeTalk to us