Skip to main content
This guide walks you through setting up NetBird API integration, which is essential for managing VPN network resources through the Selfservice portal.

​
Prerequisites

​
NetBird Account Setup

1

Create or Access NetBird Account

  1. Visit NetBird Dashboard
  2. Sign in with your account or create a new one
  3. Create a new network or select an existing network
If you’re new to NetBird, you’ll be prompted to create your first network during initial setup.
2

Find Your Network ID

Your Network ID is required for API operations. To find it:Method 1: From the URLWhen viewing your network in the NetBird dashboard, check the URL:
https://app.netbird.io/networks/[YOUR-NETWORK-ID]/overview
Method 2: From Network Settings
  1. Navigate to your network in the dashboard
  2. Go to Settings > General
  3. Look for “Network ID” or “ID” field
Copy this ID - you’ll need it for the environment configuration.
3

Create API Token

NetBird Selfservice requires an API token with appropriate permissions:
  1. In the NetBird dashboard, navigate to Settings > Access Tokens
  2. Click Create Token or Add Token
  3. Configure the token:
    • Name: “Selfservice Portal” or a descriptive name
    • Permissions: Select appropriate scopes (minimum required below)
    • Expiration: Set based on your security policy (30-90 days recommended)
  4. Click Create
  5. Copy the token immediately - it will only be shown once
Store the API token securely. It cannot be retrieved again after creation. If lost, you’ll need to generate a new token.

​
Required Permissions

The API token needs these permissions:
  • resources:read - List and view resources
  • resources:write - Create, update, and delete resources
  • groups:read - List groups for resource assignment
4

Create Required Groups

NetBird Selfservice uses two types of groups:

​
1. User Group (Employees)

This group contains users who can access the VPN resources:
  1. Navigate to Access Control > Groups
  2. Click Add Group
  3. Configure:
    • Name: “Employees” (or your preferred name)
    • Description: “Employee users with VPN access”
  4. Add your users to this group

​
2. Resource Group

This group will contain all managed resources:
  1. In Groups, click Add Group again
  2. Configure:
    • Name: “Resources for Employees” (or your preferred name)
    • Description: “Network resources managed by Selfservice portal”
  3. This group will be auto-populated by the Selfservice application
The exact group names you use must match the configuration in your .env file.
5

Find Network Name (Optional)

For display purposes, you can configure your network’s name:
  1. Go to Settings > General in your NetBird network
  2. Copy the network name
This will be displayed in the Selfservice UI to help users understand which network they’re managing.

​
Environment Configuration

1

Configure NetBird API Settings

Open your .env file and add the NetBird configuration:
# NetBird API Configuration
NETBIRD_API_URL=https://api.netbird.io
NETBIRD_API_TOKEN=nb_your_actual_api_token_here
NETBIRD_NETWORK_ID=your-network-id-here
NETBIRD_NETWORK_NAME="Your Network Name"
If you’re using self-hosted NetBird, update NETBIRD_API_URL to point to your instance.
2

Configure Group Names

Set the group names to match the groups you created in NetBird:
# NetBird Group Configuration
NETBIRD_RESOURCE_GROUP_NAME="Resources for Employees"
NETBIRD_USER_GROUP_NAME="Employees"
These names must exactly match (case-sensitive) the group names in your NetBird dashboard.
3

Configure Admin Settings

Set the admin email and egress IP:
# Admin Configuration
[email protected]
NETBIRD_EGRESS_IP=99.99.99.99
  • NETBIRD_ADMIN_EMAIL: Email address of the admin who will approve resource requests
  • NETBIRD_EGRESS_IP: Your VPN’s public egress IP (for display in the UI)
The admin email receives approval notifications and can manage all resources without approval.
4

Complete Configuration Example

Here’s a complete example of NetBird configuration in your .env file:
# NetBird VPN Configuration
NETBIRD_API_URL=https://api.netbird.io
NETBIRD_API_TOKEN=nb_1234567890abcdef1234567890abcdef
NETBIRD_NETWORK_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
NETBIRD_NETWORK_NAME="Company VPN Network"
[email protected]
NETBIRD_EGRESS_IP=203.0.113.10

# NetBird Group Names
NETBIRD_RESOURCE_GROUP_NAME="Resources for Employees"
NETBIRD_USER_GROUP_NAME="Employees"

# Security Settings
NETBIRD_ALLOWED_DOMAIN=example.com

​
Testing NetBird Connection

1

Clear Application Cache

After updating environment variables, clear the configuration cache:
php artisan config:clear
2

Test API Connection

You can test the NetBird API connection using Laravel Tinker:
php artisan tinker
Then run:
$netbird = app(App\Services\NetbirdService::class);
$groups = $netbird->listGroups();
dd($groups);
If successful, you should see a list of your NetBird groups including the ones you created.
3

Verify Group Configuration

Ensure your configured groups exist:
$netbird = app(App\Services\NetbirdService::class);
$groups = collect($netbird->listGroups());

// Check if resource group exists
$resourceGroup = $groups->firstWhere('name', config('netbird.resource_group_name'));
dd($resourceGroup);
You should see your resource group details. If null, double-check the group name matches exactly.
4

Test Resource Creation (Optional)

Create a test resource to verify full integration:
$netbird = app(App\Services\NetbirdService::class);
$groups = collect($netbird->listGroups())
    ->filter(fn($g) => $g['name'] === config('netbird.resource_group_name'))
    ->pluck('id')
    ->toArray();

$resource = $netbird->createResource(
    name: 'Test Resource',
    address: '192.168.100.1',
    description: 'Testing API integration',
    enabled: true,
    groups: $groups
);

dd($resource);
Don’t forget to delete the test resource from your NetBird dashboard after testing.

​
Group Configuration Best Practices

Single Resource Group (Recommended)Use one resource group for all managed resources:
  • Simpler to manage
  • Consistent access control
  • Easier troubleshooting
Multiple Resource Groups (Advanced)For complex environments, you might use multiple groups:
  • Separate by department or project
  • Different access levels
  • Requires custom code modifications
Department-Based Groups
  • Create groups like “Engineering”, “Sales”, “Support”
  • Assign resources to specific department groups
Access Level Groups
  • “All Employees” - basic resources
  • “Developers” - development environment resources
  • “Admins” - sensitive infrastructure resources
Hybrid Approach
  • Combine both strategies for granular control
  • Requires NetBird access policies configuration
In NetBird, create access control policies to connect user groups with resource groups:
  1. Navigate to Access Control > Policies
  2. Click Add Policy
  3. Configure:
    • Name: “Employee VPN Access”
    • Source Groups: Select your user group (“Employees”)
    • Destination Groups: Select your resource group (“Resources for Employees”)
    • Protocol: Allow all or restrict as needed
  4. Save the policy
Without an access policy connecting user and resource groups, users won’t be able to access the resources even if they’re created successfully.

​
Troubleshooting

​
”Invalid API token” error

  • Verify the token is copied correctly without extra spaces
  • Check if the token has expired
  • Ensure the token has required permissions (resources:read, resources:write, groups:read)
  • Generate a new token if needed

​
”Network not found” error

  • Verify NETBIRD_NETWORK_ID is correct
  • Check that your API token has access to this network
  • Ensure the network ID doesn’t have extra spaces or characters

​
”Group not found” error

  • Verify group names in .env match exactly (case-sensitive)
  • Check that groups exist in your NetBird dashboard
  • Run php artisan config:clear after changing group names

​
Resources not accessible by users

  • Verify an access control policy exists connecting user and resource groups
  • Check that users are members of the user group
  • Ensure resources are assigned to the correct resource group
  • Verify NetBird client is running and connected

​
Security Considerations

Protect Your API Token
  • Never commit .env to version control
  • Rotate tokens regularly (every 30-90 days)
  • Use different tokens for development and production
  • Limit token permissions to only what’s needed
  • Monitor token usage in NetBird dashboard
Production Deployment
  • Use environment variables or secrets management (e.g., AWS Secrets Manager, HashiCorp Vault)
  • Implement token rotation automation
  • Set up monitoring and alerting for API failures
  • Document your NetBird configuration in your runbook

​
Next Steps

With NetBird configured, you’re ready to:
  • User Guide - Learn how to request and manage resources
  • Admin Guide - Understand admin capabilities and workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us