Bobby
138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
# NetBird API Reference
|
|
|
|
Base URL: `https://net.dcglab.co.uk/api`
|
|
|
|
## Authentication
|
|
|
|
Header: `Authorization: Bearer <token>`
|
|
|
|
## Endpoints
|
|
|
|
### Peers
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/peers` | List all peers |
|
|
| GET | `/api/peers/{peerId}` | Get peer details |
|
|
| PUT | `/api/peers/{peerId}` | Update peer |
|
|
| DELETE | `/api/peers/{peerId}` | Delete peer |
|
|
|
|
**Peer Object Fields:**
|
|
- `id` - Unique identifier
|
|
- `name` - Peer name
|
|
- `ip` - NetBird IP address
|
|
- `connection_ip` - Public connection IP
|
|
- `connected` - Boolean connection status
|
|
- `last_seen` - ISO timestamp
|
|
- `os` - Operating system
|
|
- `hostname` - System hostname
|
|
- `groups` - Array of group objects
|
|
- `ssh_enabled` - Boolean SSH access
|
|
- `user_id` - Owner user ID
|
|
- `dns_label` - DNS name
|
|
- `approval_required` - Boolean pending approval
|
|
|
|
### Groups
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/groups` | List all groups |
|
|
| POST | `/api/groups` | Create group |
|
|
| GET | `/api/groups/{groupId}` | Get group details |
|
|
| PUT | `/api/groups/{groupId}` | Update group |
|
|
| DELETE | `/api/groups/{groupId}` | Delete group |
|
|
|
|
**Group Object Fields:**
|
|
- `id` - Unique identifier
|
|
- `name` - Group name
|
|
- `peers_count` - Number of peers
|
|
- `resources_count` - Number of resources
|
|
- `issued` - Creation source (api, etc.)
|
|
|
|
### Setup Keys
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/setup-keys` | List all setup keys |
|
|
| POST | `/api/setup-keys` | Create setup key |
|
|
| GET | `/api/setup-keys/{keyId}` | Get key details |
|
|
| PUT | `/api/setup-keys/{keyId}` | Update key |
|
|
| DELETE | `/api/setup-keys/{keyId}` | Delete key |
|
|
|
|
**Create Setup Key Body:**
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"type": "one-off" | "reusable",
|
|
"expires_in": 86400,
|
|
"auto_groups": ["group-id-1", "group-id-2"]
|
|
}
|
|
```
|
|
|
|
### Policies
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/policies` | List all policies |
|
|
| POST | `/api/policies` | Create policy |
|
|
| GET | `/api/policies/{policyId}` | Get policy details |
|
|
| PUT | `/api/policies/{policyId}` | Update policy |
|
|
| DELETE | `/api/policies/{policyId}` | Delete policy |
|
|
|
|
**Policy Rule Fields:**
|
|
- `name` - Rule name
|
|
- `description` - Rule description
|
|
- `enabled` - Boolean status
|
|
- `action` - "accept" or "drop"
|
|
- `protocol` - "tcp", "udp", "icmp", "all"
|
|
- `ports` - Array of port strings (e.g., ["80", "443"])
|
|
- `sources` - Array of source group IDs
|
|
- `destinations` - Array of destination group IDs
|
|
- `bidirectional` - Boolean
|
|
|
|
### Routes
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/routes` | List all routes |
|
|
| POST | `/api/routes` | Create route |
|
|
| GET | `/api/routes/{routeId}` | Get route details |
|
|
| PUT | `/api/routes/{routeId}` | Update route |
|
|
| DELETE | `/api/routes/{routeId}` | Delete route |
|
|
|
|
### DNS
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/dns/nameservers` | List nameserver groups |
|
|
| POST | `/api/dns/nameservers` | Create nameserver group |
|
|
| GET | `/api/dns/nameservers/{nsgroupId}` | Get nameserver group |
|
|
| PUT | `/api/dns/nameservers/{nsgroupId}` | Update nameserver group |
|
|
| DELETE | `/api/dns/nameservers/{nsgroupId}` | Delete nameserver group |
|
|
| GET | `/api/dns/settings` | Get DNS settings |
|
|
| PUT | `/api/dns/settings` | Update DNS settings |
|
|
|
|
### Users
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/users` | List all users |
|
|
| POST | `/api/users` | Create service user or invite |
|
|
| GET | `/api/users/{userId}` | Get user details |
|
|
| PUT | `/api/users/{userId}` | Update user |
|
|
| DELETE | `/api/users/{userId}` | Delete user |
|
|
| POST | `/api/users/{userId}/invite` | Resend invitation |
|
|
| POST | `/api/users/{userId}/approve` | Approve pending user |
|
|
| DELETE | `/api/users/{userId}/reject` | Reject pending user |
|
|
|
|
## Common Patterns
|
|
|
|
### Filter by Name
|
|
Many list endpoints support `?name=` query parameter for exact match filtering.
|
|
|
|
### Service Users
|
|
Set `is_service_user: true` when creating users for automation/API access.
|
|
|
|
### Auto Groups
|
|
When creating setup keys or users, specify `auto_groups` to automatically assign peers to groups.
|