Skip to main content
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
​
name
string
Filter groups by name (exact match)
curl -X GET https://api.netbird.io/api/groups \
  -H "Authorization: Token nbp_YOUR_TOKEN"
​
id
string
Unique group identifier
​
name
string
Group name
​
peers_count
integer
Number of peers in this group
​
resources_count
integer
Number of resources in this group
​
issued
string
How the group was created: api, integration, or jwt
​
peers
array
List of peer objects in the group
​
resources
array
List of resource objects in the group

​
Get a Group

Retrieve detailed information about a specific group. 
GET /api/groups/{groupId}
​
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
​
name
string
required
Group name identifier
​
peers
array
List of peer IDs to add to the group
​
resources
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"
      }
    ]
  }'

​
Update a Group

Update group name, peers, or resources. 
PUT /api/groups/{groupId}
​
groupId
string
required
The unique identifier of the group
​
name
string
required
Group name identifier
​
peers
array
Complete list of peer IDs (replaces existing peers)
​
resources
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": []
  }'
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}
​
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:
​
type
string
Resource type: peer, host, subnet, or domain
​
id
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

Build docs developers (and LLMs) love

Get started for freeTalk to us