Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/netbirdio/netbird/llms.txt

Use this file to discover all available pages before exploring further.

The Users API allows you to manage user accounts, service users, roles, and permissions in your NetBird network.

​
List All Users

Returns a list of all users in your account. 
GET /api/users
​
service_user
boolean
Filter users and return either regular users or service users
curl -X GET "https://api.netbird.io/api/users?service_user=false" \
  -H "Authorization: Token nbp_YOUR_TOKEN"
​
id
string
User ID from the identity provider
​
email
string
User’s email address
​
name
string
User’s full name from the identity provider
​
role
string
User’s NetBird account role: admin, user, or owner
​
status
string
User’s status: active, invited, or blocked
​
auto_groups
array
Group IDs to auto-assign to peers registered by this user
​
is_service_user
boolean
Indicates if this is a service user (API-only account)
​
is_blocked
boolean
Indicates if the user is blocked from using the system
​
pending_approval
boolean
Indicates if the user requires admin approval before activation

​
Get Current User

Retrieve information about the currently authenticated user. 
GET /api/users/current
Example
curl -X GET https://api.netbird.io/api/users/current \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Create a User

Create a new service user or send an invitation to a regular user. 
POST /api/users
​
email
string
User’s email address to send invite to
​
name
string
User’s full name
​
role
string
required
User’s NetBird account role: admin, user, or owner
​
auto_groups
array
required
Group IDs to auto-assign to peers registered by this user
​
is_service_user
boolean
required
Set to true to create a service user (API-only account)
curl -X POST https://api.netbird.io/api/users \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@company.com",
    "name": "Jane Doe",
    "role": "user",
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "is_service_user": false
  }'
When creating a service user with an embedded IdP, the response includes an auto-generated password field. This password is only returned once - save it securely!

​
Update a User

Update user information including role, groups, and blocked status. 
PUT /api/users/{userId}
​
userId
string
required
The unique identifier of the user
​
role
string
required
User’s NetBird account role
​
auto_groups
array
required
Group IDs to auto-assign to peers registered by this user
​
is_blocked
boolean
required
Set to true to block the user from accessing the system
Example
curl -X PUT https://api.netbird.io/api/users/google-oauth2|123456 \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0", "ch8i4ug6lnn4g9hqv7m1"],
    "is_blocked": false
  }'

​
Delete a User

Remove a user from the account. This removes the user from NetBird but typically leaves the identity provider account intact. 
DELETE /api/users/{userId}
​
userId
string
required
The unique identifier of the user
Example
curl -X DELETE https://api.netbird.io/api/users/google-oauth2|123456 \
  -H "Authorization: Token nbp_YOUR_TOKEN"
Deleting a user will:
  • Remove their access to the NetBird network
  • Delete all peers registered by the user (unless configured otherwise)
  • Remove them from all groups
This action cannot be undone.

​
User Approval

​
Approve a User

Approve a user who is pending approval (when user approval is enabled in account settings). 
POST /api/users/{userId}/approve
Example
curl -X POST https://api.netbird.io/api/users/google-oauth2|123456/approve \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Reject a User

Reject a pending user and remove them from the account. 
DELETE /api/users/{userId}/reject
Example
curl -X DELETE https://api.netbird.io/api/users/google-oauth2|123456/reject \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Resend Invitation

Resend an invitation email to a user who hasn’t accepted their invite yet. 
POST /api/users/{userId}/invite
Example
curl -X POST https://api.netbird.io/api/users/google-oauth2|123456/invite \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Change User Password

This endpoint is only available when the embedded identity provider (Dex) is enabled. Users can only change their own password.
PUT /api/users/{userId}/password
​
userId
string
required
The unique identifier of the user (must be the current user)
​
old_password
string
required
The current password
​
new_password
string
required
The new password to set
Example
curl -X PUT https://api.netbird.io/api/users/local-user-123/password \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "currentPassword123",
    "new_password": "newSecurePassword456!"
  }'

​
User Roles

NetBird supports three user roles:

Owner

Full administrative access including billing and account deletion

Admin

Manage users, peers, policies, routes, and settings

User

Limited access based on configured permissions

​
Service Users

Service users are API-only accounts without dashboard access, ideal for:
  • CI/CD automation
  • Infrastructure as Code
  • Monitoring and alerting systems
  • Third-party integrations
Service users:
  • Cannot log into the dashboard
  • Authenticate using Personal Access Tokens
  • Can be assigned limited permissions
  • Don’t count towards user limits in some plans

Build docs developers (and LLMs) love

Get started for freeTalk to us