Use service users and tokens to access NetBird's public API

Updated

Service Users

Service users are non-interactive accounts that are used to create tokens to access resources and perform actions within your organization's network using NetBird's public API.

Service users provide additional security by allowing you to limit the scope of access granted to the service user and void losing automated access to critical systems when employees leave the company.

What can you use NetBird service users and access tokens for?

Most network management operations administrators do in the NetBird Dashboard can also be done via NetBird API using service users' access tokens.

The most common usage scenarios:

  • Automated scripts: if you need to run automated scripts or infrastructure as code tools like Ansible or Terraform that configure your NetBird network.
  • Third-party integrations: if you want to integrate NetBird with a third-party service, you can use a service user to provide access to your data without giving the third-party service access to your personal account.
  • Command-line tools: if you use command-line tools like cUrl to interact with your NetBird network.

Creating a service user

To create a service user, log in to your organization's account at https://app.netbird.io, open Users in the sidebar, and select the Service Users tab.

service-user-overview

Click Create Service User and specify a name and role for the service user. User role allows read-only access, use the admin for write access.

service-user-creation-popup

Creating an access token

To create an access token, open Users in the sidebar. On the Users tab, open your own user and select Access Tokens. For a service user, open it from the Service Users tab; its Access Tokens section appears directly. Click Create Access Token.

personal-access-token-overview

From there, you can create a new token and specify expiration for the token. You won't be able to modify your token.

personal-access-creation-popup

After the token was generated successfully you will see a plain version of your token to copy and store in a secure place. Be aware that once you close the popup it is impossible to see the plain version of the token again as NetBird only stores a hashed version of the token.

personal-access-token-example

Using access tokens

Once you have created an access token, you can use it to authenticate API requests to NetBird. See NetBird API documentation for detailed usage.

For example, if you were using the API, you might include your personal access token like this:

Example request with personal access token

curl https://api.netbird.io/api/users \
  -H "Authorization: Token {token}"

With this header included, the NetBird API would authenticate your request using your personal access token and grant you access to the resources that your user has been authorized to.