Skip to main content
This guide covers administrative features and workflows for managing NetBird Selfservice. Admins have elevated privileges to approve requests, manage all resources, and oversee the VPN network.

​
Admin Role Overview

Admins are identified by their email address matching the NETBIRD_ADMIN_EMAIL environment variable. Admin capabilities include:
  • Creating resources without approval
  • Approving or denying user requests
  • Editing and deleting any resource (not just owned resources)
  • Viewing complete activity logs
  • Managing all users’ resources
  • Receiving approval request notifications
Admin privileges are powerful. Only trusted personnel should have admin access.

​
Configuring Admin Access

​
Setting the Admin Email

Admin access is configured in your .env file: 
# Admin Configuration
[email protected]
1

Choose Admin Email

Select the email address of the person who will be the primary admin.
This must match the email address used for Google OAuth authentication.
2

Update Environment File

Edit your .env file and set the NETBIRD_ADMIN_EMAIL value:
[email protected]
3

Clear Cache and Restart

Apply the configuration change:
php artisan config:clear
If using a process manager, restart your application.
4

Verify Admin Access

Sign in with the admin email address and verify you see admin-specific features:
  • “Approve” buttons on pending requests
  • Access to all resources (not just your own)
  • Activity log with all user actions

​
Multiple Admins

Currently, the system supports a single admin email. For multiple admins, you have these options:
Modify the admin check logic to support multiple admins:
  1. Update .env with comma-separated emails:
[email protected],[email protected]
  1. Modify admin check logic in your application code to parse and check against the array.
This requires code changes and testing. Not recommended unless you’re comfortable with Laravel development.
Implement a proper role-based access control system:
  • Add is_admin boolean to users table
  • Create admin management interface
  • Update authorization logic throughout the application
This provides the most flexibility but requires significant custom development.

​
Approval Workflow

When users submit resource requests, admins receive notifications and must approve or deny them.

​
Email Approval Process

1

Receive Notification Email

When a user submits a request, you receive an email with:
  • Resource name and address
  • Description and purpose
  • Requester’s name and email
  • Request date
  • Two action links: Approve and Deny
Subject line: New Resource for Approval: [Resource Name]
2

Review Request Details

Evaluate the request based on:Technical Validity
  • Is the address format correct?
  • Is it a customer network or legitimate resource?
  • Does the CIDR range make sense?
Security Considerations
  • Is the request from an authorized user?
  • Is the scope appropriate (not overly broad)?
  • Does it follow security policies?
Business Context
  • Is there a valid business need?
  • Is this related to an active project?
  • Has the customer approved this access?
3

Take Action

Click one of the action links in the email:Approve
  • Resource is created in NetBird immediately
  • User receives approval notification
  • Resource appears in user’s dashboard
  • Activity is logged
Deny
  • Request is marked as denied
  • User receives rejection notification
  • Request appears in user’s history
  • Activity is logged
Approval links are signed URLs valid for 7 days. After expiration, you’ll need to manage requests through the web portal.
4

User Notification

The requester automatically receives an email with the decision:
  • If Approved: Instructions for accessing the resource
  • If Denied: Notification of rejection and next steps

​
Portal Approval Process

You can also manage requests through the web portal:
1

Sign In to Portal

Navigate to the NetBird Selfservice portal and sign in with your admin email.
2

View Pending Requests

Go to the “Pending Requests” section or filter resources by “Pending” status.You’ll see all pending requests from all users.
3

Review Request

Click on a pending request to view full details:
  • Complete resource information
  • Requester details
  • Submission timestamp
  • Request description
4

Approve or Deny

Click the appropriate button:
  • “Approve” - Creates the resource immediately
  • “Deny” - Rejects the request
The requester is notified automatically via email.

​
Creating Resources as Admin

Admins can create resources directly without going through the approval process:
1

Click 'New Resource'

From the dashboard, click “New Resource” or “Add Resource”.
2

Fill in Details

Complete the resource form:
Name: Customer XYZ Production Network
Address: 172.16.50.0/24
Description: Full production network access for Customer XYZ
             support project. Contact: [email protected]
Enabled: ✓
3

Submit

Click “Create” or “Submit”.
As an admin, your resources are created immediately without approval. They appear instantly in NetBird.

​
Bulk Resource Creation

For creating many resources at once:
Create multiple resources through the UI in succession:
  1. Fill out the form
  2. Submit
  3. Immediately click “New Resource” again
  4. Repeat for each resource
This is practical for up to ~10 resources.
For very large imports:
  1. Sign in to NetBird dashboard
  2. Use NetBird’s bulk import features (if available)
  3. Resources created in NetBird will be visible but not tracked in Selfservice
Resources created directly in NetBird bypass the Selfservice tracking and ownership system.
Use Laravel Tinker or a custom script:
php artisan tinker

$admin = User::where('email', config('netbird.admin_email'))->first();
$action = app(App\Actions\CreateResourceAction::class);

// Get resource group ID
$netbird = app(App\Services\NetbirdService::class);
$groupId = collect($netbird->listGroups())
    ->firstWhere('name', config('netbird.resource_group_name'))['id'];

// Create resources
$resources = [
    ['name' => 'Resource 1', 'address' => '10.0.1.0/24'],
    ['name' => 'Resource 2', 'address' => '10.0.2.0/24'],
    // ... more resources
];

foreach ($resources as $resource) {
    $action->execute(
        name: $resource['name'],
        address: $resource['address'],
        description: 'Bulk imported',
        enabled: true,
        groupId: $groupId,
        user: $admin
    );
}

​
Managing All Resources

As an admin, you can manage resources created by any user:

​
Viewing All Resources

  • Dashboard View: See all resources from all users
  • Filter by User: Find resources by creator
  • Filter by Status: View active, disabled, or pending resources
  • Search: Search by name or address

​
Editing Any Resource

1

Select Resource

Click on any resource in the dashboard.
2

Click Edit

Click the “Edit” button (available for all resources when signed in as admin).
3

Modify Details

Update:
  • Name
  • Address
  • Description
  • Enabled status
4

Save Changes

Click “Save”.Changes are:
  • Applied immediately in NetBird
  • Logged in activity log
  • Attributed to your admin account

​
Deleting Any Resource

1

Select Resource

Click on the resource to delete.
2

Click Delete

Click “Delete” or “Remove”.
3

Confirm

Confirm the deletion.
Deletion is permanent and removes the resource from NetBird immediately. Users will lose access instantly.

​
Activity Logs

Admins have access to comprehensive activity logs:

​
What’s Logged

All resource-related actions are logged:
  • Resource created (admin or user)
  • Resource requested (non-admin user)
  • Request approved
  • Request denied
  • Resource updated
  • Resource deleted
  • Resource enabled/disabled

​
Log Information

Each log entry includes:
  • Timestamp: When the action occurred
  • Action: What was done
  • Resource: Name and address
  • User: Who performed the action
  • Changes: What changed (for updates)
  • NetBird ID: NetBird resource identifier

​
Viewing Logs

1

Access Activity Log

Navigate to “Activity Log” or “Logs” in the portal menu.
2

Filter Logs

Use filters to find specific activities:
  • By date range
  • By user
  • By action type
  • By resource name
3

Review Details

Click on a log entry to see full details including before/after values for updates.

​
Log Retention

Logs are stored in the application database:
  • No automatic deletion
  • Can be manually cleaned up if needed
  • Consider implementing log rotation for long-term deployments
Regularly review activity logs to:
  • Identify unusual patterns
  • Audit resource changes
  • Troubleshoot issues
  • Monitor user behavior

​
User Management

While there’s no built-in user management interface, admins can manage users through the database:

​
Viewing Users

Users are automatically created when they first sign in via OAuth: 
php artisan tinker

// List all users
App\Models\User::all();

// Find specific user
App\Models\User::where('email', '[email protected]')->first();

// Count total users
App\Models\User::count();

​
User Information

Each user record contains:
  • Name (from OAuth provider)
  • Email
  • Google ID (OAuth identifier)
  • Avatar URL
  • Created timestamp

​
Removing Users

If you need to remove a user:
  1. Remove from OAuth provider: Disable their account in Google Workspace
  2. Optional: Delete user from database: 
    php artisan tinker

$user = App\Models\User::where('email', '[email protected]')->first();
$user->delete();
Deleting a user doesn’t delete their resources. Consider reassigning or removing their resources first.

​
Email Configuration

Admins need to ensure email notifications work properly:

​
Testing Email

Verify email configuration: 
php artisan tinker

// Send test email
Mail::raw('Test email from NetBird Selfservice', function($message) {
    $message->to(config('netbird.admin_email'))
            ->subject('Test Email');
});

​
Email Providers

Configure your email provider in .env: 
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME="${APP_NAME}"
For Gmail, you need to use an App Password, not your regular password.

​
Security Best Practices

Protect Admin Credentials
  • Use strong, unique password for admin email
  • Enable 2FA on admin Google account
  • Don’t share admin credentials
  • Regularly audit admin access
Limit Admin Access
  • Only designate necessary personnel as admins
  • Use shared email alias for multiple admins
  • Document who has admin access
  • Review admin activity regularly
Always Verify
  • Confirm requester identity
  • Validate business need
  • Check with project managers if unsure
  • Verify customer authorization
Security Checks
  • Reject overly broad ranges (e.g., 0.0.0.0/0)
  • Question suspicious addresses
  • Verify domains are legitimate
  • Check for typos in addresses
Documentation
  • Require detailed descriptions
  • Ask for ticket numbers
  • Note any special circumstances
  • Document approval reasoning
Weekly
  • Review pending requests
  • Process approvals promptly
  • Check for abandoned requests
Monthly
  • Audit all active resources
  • Remove unused resources
  • Review activity logs
  • Verify users still need access
Quarterly
  • Full security audit
  • Review admin access
  • Update documentation
  • Test disaster recovery procedures
If You Suspect Compromise
  1. Immediately disable suspicious resources
  2. Review recent activity logs
  3. Check for unauthorized changes
  4. Rotate NetBird API token
  5. Force re-authentication of all users
  6. Contact security team
If Admin Account Compromised
  1. Disable OAuth account immediately
  2. Change NETBIRD_ADMIN_EMAIL in .env
  3. Review all recent admin actions
  4. Audit all resources for unauthorized changes
  5. Rotate all credentials
  6. Notify security team and users

​
Troubleshooting

​
Admin Features Not Visible

Problem: Signed in with admin email but don’t see admin features Solutions:
  1. Verify email in .env matches exactly: 
    grep NETBIRD_ADMIN_EMAIL .env
  2. Clear configuration cache: 
    php artisan config:clear
  3. Sign out and sign back in
  4. Check that email case matches (some systems are case-sensitive)

​
Approval Emails Not Received

Problem: No email notifications when users submit requests Solutions:
  1. Check spam/junk folder
  2. Verify NETBIRD_ADMIN_EMAIL is correct
  3. Test email configuration: 
    php artisan tinker
Mail::raw('Test', fn($m) => $m->to(config('netbird.admin_email'))->subject('Test'));
  4. Check Laravel logs: storage/logs/laravel.log
  5. Verify mail provider settings in .env
Problem: Clicked approval link but got “expired” or “invalid” error Solutions:
  • Approval links expire after 7 days
  • Sign in to the portal and approve from there
  • Request user to resubmit if needed

​
Can’t Delete Resource

Problem: Error when trying to delete a resource Solutions:
  1. Check NetBird API connectivity
  2. Verify NetBird API token hasn’t expired
  3. Check if resource was already deleted in NetBird
  4. Review application logs for specific errors

​
Best Practices for Admins

Timely Approvals
  • Process requests within 1 business day
  • Set up email notifications to your phone
  • Check pending requests daily
  • Communicate delays to users
Clear Communication
  • Provide reasons when denying requests
  • Suggest corrections for invalid requests
  • Document approval policies
  • Be available for questions
Documentation
  • Maintain internal approval guidelines
  • Document common resources and purposes
  • Keep contact list for verification
  • Record policy exceptions and reasoning
Monitoring
  • Review activity logs weekly
  • Watch for unusual patterns
  • Audit resources monthly
  • Track metrics (requests, approvals, denials)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us