Users API

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

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"

curl -X GET "https://api.netbird.io/api/users?service_user=true" \
  -H "Authorization: Token nbp_YOUR_TOKEN"

[
  {
    "id": "google-oauth2|277474792786460067937",
    "email": "demo@netbird.io",
    "name": "Tom Schulz",
    "role": "admin",
    "status": "active",
    "last_login": "2023-05-05T09:00:35.477782Z",
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "is_current": true,
    "is_service_user": false,
    "is_blocked": false,
    "pending_approval": false,
    "permissions": {
      "is_restricted": false,
      "modules": {
        "peers": {"read": true, "create": true, "update": true, "delete": true}
      }
    }
  }
]

string

User ID from the identity provider

string

User’s email address

string

User’s full name from the identity provider

string

User’s NetBird account role: admin, user, or owner

string

User’s status: active, invited, or blocked

array

Group IDs to auto-assign to peers registered by this user

boolean

Indicates if this is a service user (API-only account)

boolean

Indicates if the user is blocked from using the system

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

string

User’s email address to send invite to

string

User’s full name

string

required

User’s NetBird account role: admin, user, or owner

array

required

Group IDs to auto-assign to peers registered by this 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
  }'

curl -X POST https://api.netbird.io/api/users \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ci-bot@company.com",
    "name": "CI/CD Service",
    "role": "user",
    "auto_groups": [],
    "is_service_user": true
  }'

{
  "id": "service-user-abc123",
  "email": "ci-bot@company.com",
  "password": "auto-generated-password",
  "name": "CI/CD Service",
  "role": "user",
  "status": "active",
  "auto_groups": [],
  "is_service_user": true,
  "is_blocked": 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}

string

required

The unique identifier of the user

string

required

User’s NetBird account role

array

required

Group IDs to auto-assign to peers registered by this user

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}

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

string

required

The unique identifier of the user (must be the current user)

string

required

The current 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

Getting Started

Resources

List All Users

Get Current User

Create a User

Update a User

Delete a User

User Approval

Approve a User

Reject a User

Resend Invitation

Change User Password

User Roles

Owner

Admin

User

Service Users

​List All Users

​Get Current User

​Create a User

​Update a User

​Delete a User

​User Approval

​Approve a User

​Reject a User

​Resend Invitation

​Change User Password

​User Roles

Owner

Admin

User

​Service Users

List All Users

Get Current User

Create a User

Update a User

Delete a User

User Approval

Approve a User

Reject a User

Resend Invitation

Change User Password

User Roles

Service Users