The Events API provides access to audit logs and activity events in your NetBird network, enabling compliance, monitoring, and security analysis.
Audit Events Audit events track administrative actions and system changes.
List All Audit Events curl -X GET https://api.netbird.io/api/events/audit \ -H "Authorization: Token nbp_YOUR_TOKEN"
When the event occurred (ISO 8601 format)
Human-readable description of the activity
Machine-readable activity code
ID of the user who triggered the event
Name of the user who triggered the event
Email of the user who triggered the event
ID of the resource affected by the event
Additional event metadata
Activity Codes Events are categorized by activity codes for easy filtering and monitoring.
User Events User Management
User Invites
user.join user.invite user.create user.delete user.block user.unblock user.role.update user.approve user.reject user.peer.login user.password.change
Peer Events Peer Management
Peer Configuration
Peer Approval
Jobs
peer.user.add peer.setupkey.add peer.group.add peer.group.delete user.peer.delete peer.rename peer.ip.update
Policy & Rule Events policy.add policy.update policy.delete rule.add rule.update rule.delete posture.check.create posture.check.update posture.check.delete
Network Events route.add route.update route.delete
DNS Events nameserver.group.add nameserver.group.update nameserver.group.delete dns.setting.disabled.management.group.add dns.setting.disabled.management.group.delete
Setup Key Events setupkey.add setupkey.update setupkey.revoke setupkey.overuse setupkey.delete
Token Events personal.access.token.create personal.access.token.delete
Account Events Account Management
Account Settings
account.create account.delete dashboard.login transferred.owner.role
Integration Events integration.create integration.update integration.delete identityprovider.create identityprovider.update identityprovider.delete service.create service.update service.delete
Network Traffic Events Network traffic events are a Cloud-only experimental feature that tracks network flows between peers.
List Network Traffic Events GET /api/events/network-traffic
Items per page (max 50000)
Filter by reporter (peer) ID
Filter by protocol (1=ICMP, 6=TCP, 17=UDP)
Filter by event type: TYPE_START, TYPE_END, TYPE_DROP
Filter by connection: P2P or ROUTED
Filter by direction: INGRESS, EGRESS
Search user email, source/destination names and addresses
Start date filter (ISO 8601)
End date filter (ISO 8601)
curl -X GET "https://api.netbird.io/api/events/network-traffic?page=1&page_size=100" \ -H "Authorization: Token nbp_YOUR_TOKEN"
Reverse Proxy Access Logs View access logs for reverse proxy services (NetBird Cloud feature).
List Proxy Access Logs sort_by
string
default: "timestamp"
Field to sort by: timestamp, url, host, path, method, status_code, duration, source_ip, user_id, auth_method, reason
General search across fields
Filter by HTTP status code
Start date filter (RFC3339 format)
End date filter (RFC3339 format)
curl -X GET "https://api.netbird.io/api/events/proxy?page=1&page_size=50" \ -H "Authorization: Token nbp_YOUR_TOKEN"
Event Monitoring Strategies Security Monitoring Monitor security-relevant events:
# Watch for user account changes activity_code: user.role.update activity_code: user.block activity_code: user.create # Watch for policy changes activity_code: policy.delete activity_code: rule.update # Watch for setup key usage activity_code: setupkey.overuse activity_code: peer.setupkey.add
Compliance Auditing Track administrative actions:
# Configuration changes activity_code: account.setting. * activity_code: network. * activity_code: route. * # Access control changes activity_code: policy. * activity_code: group. *
Operational Monitoring Monitor network health:
# Peer connectivity activity_code: peer.user.add activity_code: user.peer.delete activity_code: peer.login.expire # DNS changes activity_code: dns.zone. * activity_code: nameserver.group. *
Integration Examples SIEM Integration Forward events to your SIEM:
import requests import time def fetch_events (): response = requests.get( "https://api.netbird.io/api/events/audit" , headers = { "Authorization" : f "Token { token } " } ) return response.json() # Poll for new events every minute while True : events = fetch_events() for event in events: send_to_siem(event) time.sleep( 60 )
Webhook Notifications Send critical events to Slack/Discord:
def check_critical_events ( events ): critical_codes = [ "user.role.update" , "policy.delete" , "account.delete" ] for event in events: if event[ "activity_code" ] in critical_codes: notify_team(event)
Best Practices Regular audits - Review audit logs regularly for suspicious activity
Alert on critical events - Set up monitoring for security-relevant changes
Retain logs - Export and archive events for compliance requirements
Filter effectively - Use activity codes to focus on relevant events
Monitor anomalies - Watch for unusual patterns in event data
