Groups API - NetBird

Groups are used to organize peers and resources, making it easier to apply policies, routes, and access controls across multiple devices.

List All Groups

Returns a list of all groups in your network.

GET /api/groups

string

Filter groups by name (exact match)

curl -X GET https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN"

curl -X GET "https://api.netbird.io/api/groups?name=developers" \
  -H "Authorization: Token nbp_YOUR_TOKEN"

[
  {
    "id": "ch8i4ug6lnn4g9hqv7m0",
    "name": "developers",
    "peers_count": 5,
    "resources_count": 3,
    "issued": "api",
    "peers": [
      {
        "id": "chacbco6lnnbn6cg5s90",
        "name": "laptop-01"
      },
      {
        "id": "chacbco6lnnbn6cg5s91",
        "name": "desktop-02"
      }
    ],
    "resources": [
      {
        "id": "res_123",
        "type": "host"
      }
    ]
  }
]

string

Unique group identifier

string

Group name

integer

Number of peers in this group

integer

Number of resources in this group

string

How the group was created: api, integration, or jwt

array

List of peer objects in the group

array

List of resource objects in the group

Get a Group

Retrieve detailed information about a specific group.

GET /api/groups/{groupId}

string

required

The unique identifier of the group

Example

curl -X GET https://api.netbird.io/api/groups/ch8i4ug6lnn4g9hqv7m0 \
  -H "Authorization: Token nbp_YOUR_TOKEN"

Create a Group

Create a new group with specified peers and resources.

POST /api/groups

string

required

Group name identifier

array

List of peer IDs to add to the group

array

List of resource objects to add to the group

curl -X POST https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-servers",
    "peers": [
      "chacbco6lnnbn6cg5s90",
      "chacbco6lnnbn6cg5s91"
    ],
    "resources": [
      {
        "id": "peer_abc123",
        "type": "peer"
      }
    ]
  }'

{
  "id": "ch8i4ug6lnn4g9hqv7m1",
  "name": "production-servers",
  "peers_count": 2,
  "resources_count": 1,
  "issued": "api",
  "peers": [
    {
      "id": "chacbco6lnnbn6cg5s90",
      "name": "server-01"
    },
    {
      "id": "chacbco6lnnbn6cg5s91",
      "name": "server-02"
    }
  ],
  "resources": [
    {
      "id": "peer_abc123",
      "type": "peer"
    }
  ]
}

Update a Group

Update group name, peers, or resources.

PUT /api/groups/{groupId}

string

required

The unique identifier of the group

string

required

Group name identifier

array

Complete list of peer IDs (replaces existing peers)

array

Complete list of resource objects (replaces existing resources)

curl -X PUT https://api.netbird.io/api/groups/ch8i4ug6lnn4g9hqv7m0 \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-servers-updated",
    "peers": [
      "chacbco6lnnbn6cg5s90",
      "chacbco6lnnbn6cg5s91",
      "chacbco6lnnbn6cg5s92"
    ],
    "resources": []
  }'

{
  "id": "ch8i4ug6lnn4g9hqv7m0",
  "name": "production-servers-updated",
  "peers_count": 3,
  "resources_count": 0,
  "peers": [
    {"id": "chacbco6lnnbn6cg5s90", "name": "server-01"},
    {"id": "chacbco6lnnbn6cg5s91", "name": "server-02"},
    {"id": "chacbco6lnnbn6cg5s92", "name": "server-03"}
  ],
  "resources": []
}

Updating a group replaces the entire peer and resource lists. Make sure to include all peers and resources you want to keep.

Delete a Group

Remove a group from the network.

DELETE /api/groups/{groupId}

string

required

The unique identifier of the group

Example

curl -X DELETE https://api.netbird.io/api/groups/ch8i4ug6lnn4g9hqv7m0 \
  -H "Authorization: Token nbp_YOUR_TOKEN"

Deleting a group will:

Remove the group from all policies
Remove the group from all routes
Remove the group from user auto-groups
NOT delete the peers or resources in the group

Group Types

Groups can be created through different methods:

API Groups

Created and managed via the API or dashboard

Integration Groups

Automatically synced from identity providers (Okta, Azure AD, etc.)

JWT Groups

Extracted from JWT claims during user authentication

Common Use Cases

Organizing by Department

Create groups for different teams:

# Engineering team
curl -X POST https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "engineering", "peers": [...]}'

# Sales team
curl -X POST https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "sales", "peers": [...]}'

Organizing by Environment

Separate production, staging, and development:

curl -X POST https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "peers": ["prod-server-01", "prod-server-02"]
  }'

Organizing by Location

Group peers by geographic location:

curl -X POST https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "us-east",
    "peers": [...]
  }'

Resource Types

Groups can contain different resource types:

string

Resource type: peer, host, subnet, or domain

string

Unique resource identifier

Example Resources

{
  "resources": [
    {"id": "peer_abc", "type": "peer"},
    {"id": "host_xyz", "type": "host"},
    {"id": "net_123", "type": "subnet"}
  ]
}

Best Practices

Use descriptive names - Name groups based on their purpose (e.g., “engineering-laptops”, “production-databases”)

Keep groups focused - Create smaller, specific groups rather than large, generic ones

Document group purpose - Maintain documentation on what each group represents

Regular audits - Periodically review group memberships to ensure accuracy

Use integration groups - Leverage identity provider groups when possible for automatic synchronization

​List All Groups

​Get a Group

​Create a Group

​Update a Group

​Delete a Group

​Group Types

API Groups

Integration Groups

JWT Groups

​Common Use Cases

​Organizing by Department

​Organizing by Environment

​Organizing by Location

​Resource Types

​Best Practices

List All Groups

Get a Group

Create a Group

Update a Group

Delete a Group

Group Types

Common Use Cases

Organizing by Department

Organizing by Environment

Organizing by Location

Resource Types

Best Practices