Policies API

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": "ch8i4ug6lnn4g9hqv7mg",
    "name": "Allow Engineering to Production",
    "description": "Allows engineering team access to production servers",
    "enabled": true,
    "source_posture_checks": ["chacdk86lnnboviihd70"],
    "rules": [
      {
        "id": "ch8i4ug6lnn4g9hqv7mh",
        "name": "HTTPS Access",
        "description": "Allow HTTPS traffic",
        "enabled": true,
        "action": "accept",
        "bidirectional": false,
        "protocol": "tcp",
        "ports": ["443"],
        "sources": [
          {
            "id": "ch8i4ug6lnn4g9hqv797",
            "name": "engineering",
            "peers_count": 5
          }
        ],
        "destinations": [
          {
            "id": "ch8i4ug6lnn4g9h7v7m0",
            "name": "production",
            "peers_count": 3
          }
        ]
      }
    ]
  }
]

string

Unique policy identifier

string

Policy name

string

Policy description

boolean

Whether the policy is active

array

Posture check IDs applied to source groups

array

List of policy rules defining access controls

Get a Policy

Retrieve detailed information about a specific policy.

GET /api/policies/{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

string

required

Policy name

string

Policy description

boolean

required

Whether the policy is active

array

Posture check IDs to apply to source groups

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"]
      }
    ]
  }'

{
  "id": "ch8i4ug6lnn4g9hqv7mi",
  "name": "Allow SSH Access",
  "description": "Allow admins to SSH into servers",
  "enabled": true,
  "source_posture_checks": [],
  "rules": [
    {
      "id": "ch8i4ug6lnn4g9hqv7mj",
      "name": "SSH Rule",
      "enabled": true,
      "action": "accept",
      "protocol": "tcp",
      "ports": ["22"],
      "sources": [...],
      "destinations": [...]
    }
  ]
}

Update a Policy

Update an existing policy and its rules.

PUT /api/policies/{policyId}

string

required

The unique identifier of the policy

string

required

Policy name

boolean

required

Whether the policy is active

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}

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

string

required

Rule name

string

Rule description

boolean

required

Whether the rule is active

string

required

Action to take: accept or drop

boolean

required

Whether the rule applies in both directions

string

required

Protocol type: all, tcp, udp, icmp, or netbird-ssh

array

List of port numbers (for TCP/UDP)

array

List of port range objects with start and end fields

array

required

Source group IDs

array

required

Destination group IDs

object

Source resource object (alternative to sources)

object

Destination resource object (alternative to destinations)

Protocol Examples

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

{
  "protocol": "tcp",
  "port_ranges": [
    {"start": 8000, "end": 8999}
  ]
}

{
  "protocol": "all"
}

{
  "protocol": "icmp"
}

{
  "protocol": "netbird-ssh"
}

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

Getting Started

Resources

List All Policies

Get a Policy

Create a Policy

Update a Policy

Delete a Policy

Policy Rules

Rule Fields

Protocol Examples

Policy Actions

Accept

Drop

Bidirectional Rules

Posture Checks

Common Policy Patterns

Allow All Within Group

Database Access

Zero Trust Access

Best Practices

​List All Policies

​Get a Policy

​Create a Policy

​Update a Policy

​Delete a Policy

​Policy Rules

​Rule Fields

​Protocol Examples

​Policy Actions

Accept

Drop

​Bidirectional Rules

​Posture Checks

​Common Policy Patterns

​Allow All Within Group

​Database Access

​Zero Trust Access

​Best Practices

List All Policies

Get a Policy

Create a Policy

Update a Policy

Delete a Policy

Policy Rules

Rule Fields

Protocol Examples

Policy Actions

Bidirectional Rules

Posture Checks

Common Policy Patterns

Allow All Within Group

Database Access

Zero Trust Access

Best Practices