Skip to main content

​
Overview

The NetbirdService class provides a PHP interface for interacting with the NetBird API. It handles resource management, group operations, and API authentication for the NetBird Self-Service platform.
This service uses Laravel’s HTTP client and automatically handles authentication via bearer token.

​
Constructor

​
__construct()

Initializes a new NetbirdService instance with configuration from the application’s config files. 
public function __construct()
Configuration Required: The constructor reads the following configuration values:
  • netbird.api_url - Base URL for the NetBird API
  • netbird.api_token - API authentication token
  • netbird.network_id - Network ID for resource operations
Ensure these configuration values are set in your config/netbird.php file before using this service.
Example: 
use App\Services\NetbirdService;

$netbird = new NetbirdService();

​
Resource Management

​
listResources()

Retrieves all resources in the configured network. 
public function listResources(): array
Return Type:
​
return
array<int, array>
Array of resource objects, each containing:
Example: 
$netbird = new NetbirdService();
$resources = $netbird->listResources();

foreach ($resources as $resource) {
    echo "Resource: {$resource['name']} ({$resource['address']})\n";
}
Errors: Throws Illuminate\Http\Client\RequestException if the API request fails.

​
getResource()

Retrieves a single resource by its ID. 
public function getResource(string $resourceId): array
Parameters:
​
resourceId
string
required
The unique identifier of the resource to retrieve
Return Type:
​
return
array
Resource object containing:
Example: 
$netbird = new NetbirdService();
$resource = $netbird->getResource('res_abc123');

echo "Name: {$resource['name']}\n";
echo "Address: {$resource['address']}\n";
echo "Enabled: " . ($resource['enabled'] ? 'Yes' : 'No') . "\n";
Errors: Throws Illuminate\Http\Client\RequestException if:
  • The resource ID is not found
  • The API request fails
  • Authentication is invalid

​
createResource()

Creates a new resource in the network. 
public function createResource(
    string $name,
    string $address,
    ?string $description = null,
    bool $enabled = true,
    array $groups = []
): array
Parameters:
​
name
string
required
Display name for the new resource
​
address
string
required
Network address or hostname for the resource (e.g., 192.168.1.100 or server.example.com)
​
description
string|null
default:"null"
Optional description of the resource
​
enabled
bool
default:"true"
Whether the resource should be enabled upon creation
​
groups
array<string>
default:"[]"
Array of group IDs to associate with this resource
Return Type:
​
return
array
The newly created resource object with all fields populated, including the generated id
Example: 
$netbird = new NetbirdService();

$resource = $netbird->createResource(
    name: 'Database Server',
    address: '10.0.1.50'
);

echo "Created resource with ID: {$resource['id']}\n";
Errors: Throws Illuminate\Http\Client\RequestException if:
  • Required parameters are missing or invalid
  • The address is already in use
  • The API request fails
  • Authentication is invalid

​
updateResource()

Updates an existing resource with new values. 
public function updateResource(
    string $resourceId,
    string $name,
    string $address,
    ?string $description = null,
    bool $enabled = true,
    array $groups = []
): array
Parameters:
​
resourceId
string
required
The unique identifier of the resource to update
​
name
string
required
Updated display name for the resource
​
address
string
required
Updated network address or hostname for the resource
​
description
string|null
default:"null"
Updated description of the resource
​
enabled
bool
default:"true"
Whether the resource should be enabled
​
groups
array<string>
default:"[]"
Updated array of group IDs to associate with this resource
All resource fields are updated with each call. To preserve existing values, retrieve the current resource first using getResource() and pass the existing values for fields you don’t want to change.
Return Type:
​
return
array
The updated resource object with all current values
Example: 
$netbird = new NetbirdService();

// Get current resource
$current = $netbird->getResource('res_abc123');

// Update with new values
$updated = $netbird->updateResource(
    resourceId: 'res_abc123',
    name: 'Production Database Server',
    address: '10.0.1.51',
    description: $current['description'],
    enabled: $current['enabled'],
    groups: $current['groups']
);
Errors: Throws Illuminate\Http\Client\RequestException if:
  • The resource ID is not found
  • Required parameters are missing or invalid
  • The API request fails
  • Authentication is invalid

​
deleteResource()

Deletes a resource from the network. 
public function deleteResource(string $resourceId): bool
Parameters:
​
resourceId
string
required
The unique identifier of the resource to delete
Return Type:
​
return
bool
Returns true if the resource was successfully deleted
This operation is permanent and cannot be undone. Ensure you have the correct resource ID before calling this method.
Example: 
$netbird = new NetbirdService();

try {
    $success = $netbird->deleteResource('res_abc123');
    
    if ($success) {
        echo "Resource deleted successfully\n";
    }
} catch (\Illuminate\Http\Client\RequestException $e) {
    echo "Failed to delete resource: {$e->getMessage()}\n";
}
Errors: Throws Illuminate\Http\Client\RequestException if:
  • The resource ID is not found
  • The resource cannot be deleted due to dependencies
  • The API request fails
  • Authentication is invalid

​
Group Management

​
listGroups()

Retrieves all available groups from the NetBird API. 
public function listGroups(): array
Return Type:
​
return
array<int, array>
Array of group objects, each containing:
Use this method to get available group IDs when creating or updating resources.
Example: 
$netbird = new NetbirdService();
$groups = $netbird->listGroups();

echo "Available groups:\n";
foreach ($groups as $group) {
    echo "- {$group['name']} (ID: {$group['id']})\n";
}
Errors: Throws Illuminate\Http\Client\RequestException if the API request fails.

​
HTTP Client Configuration

​
Authentication

The service uses token-based authentication with the NetBird API. Authentication is handled automatically through the private client() method. Headers: 
Authorization: Token {api_token}
Accept: application/json
Content-Type: application/json

​
Base URL

All API requests are made relative to the configured base URL (netbird.api_url). Example Configuration:
config/netbird.php
return [
    'api_url' => env('NETBIRD_API_URL', 'https://api.netbird.io'),
    'api_token' => env('NETBIRD_API_TOKEN'),
    'network_id' => env('NETBIRD_NETWORK_ID'),
];

​
Error Handling

All methods call $response->throw() which throws an Illuminate\Http\Client\RequestException for failed HTTP requests (4xx and 5xx status codes). Example Error Handling: 
use Illuminate\Http\Client\RequestException;

$netbird = new NetbirdService();

try {
    $resource = $netbird->getResource('invalid_id');
} catch (RequestException $e) {
    $statusCode = $e->response->status();
    $errorBody = $e->response->json();
    
    echo "API Error ({$statusCode}): {$errorBody['message']}\n";
}

​
Usage Examples

​
Complete Resource Lifecycle

use App\Services\NetbirdService;

$netbird = new NetbirdService();

// List all available groups
$groups = $netbird->listGroups();
$groupId = $groups[0]['id'];

// Create a new resource
$resource = $netbird->createResource(
    name: 'Web Server',
    address: '10.0.2.100',
    description: 'Production web server',
    enabled: true,
    groups: [$groupId]
);

$resourceId = $resource['id'];
echo "Created resource: {$resourceId}\n";

// Retrieve the resource
$retrieved = $netbird->getResource($resourceId);
echo "Retrieved: {$retrieved['name']}\n";

// Update the resource
$updated = $netbird->updateResource(
    resourceId: $resourceId,
    name: 'Web Server - Updated',
    address: '10.0.2.101',
    description: 'Updated production web server',
    enabled: true,
    groups: [$groupId]
);
echo "Updated address to: {$updated['address']}\n";

// List all resources
$allResources = $netbird->listResources();
echo "Total resources: " . count($allResources) . "\n";

// Delete the resource
$deleted = $netbird->deleteResource($resourceId);
echo "Deleted: " . ($deleted ? 'success' : 'failed') . "\n";

​
Bulk Operations

use App\Services\NetbirdService;

$netbird = new NetbirdService();

// Create multiple resources
$servers = [
    ['name' => 'DB Primary', 'address' => '10.0.1.10'],
    ['name' => 'DB Replica', 'address' => '10.0.1.11'],
    ['name' => 'Cache Server', 'address' => '10.0.1.20'],
];

$createdResources = [];

foreach ($servers as $server) {
    $resource = $netbird->createResource(
        name: $server['name'],
        address: $server['address'],
        enabled: true
    );
    
    $createdResources[] = $resource['id'];
}

echo "Created " . count($createdResources) . " resources\n";

​
Conditional Resource Management

use App\Services\NetbirdService;

$netbird = new NetbirdService();

// Get all resources
$resources = $netbird->listResources();

// Disable all resources matching a pattern
foreach ($resources as $resource) {
    if (str_contains($resource['name'], 'Staging')) {
        $netbird->updateResource(
            resourceId: $resource['id'],
            name: $resource['name'],
            address: $resource['address'],
            description: $resource['description'],
            enabled: false, // Disable staging resources
            groups: $resource['groups']
        );
        
        echo "Disabled: {$resource['name']}\n";
    }
}

​
Source Reference

File: app/Services/NetbirdService.php Namespace: App\Services Dependencies:
  • Illuminate\Http\Client\PendingRequest
  • Illuminate\Support\Facades\Http

Build docs developers (and LLMs) love

Get started for freeTalk to us