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

## 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 are Service Users used for?

Service users are typically used to authenticate requests to a web service on behalf of an application or a service. They are an alternative to using a personal account, and can provide additional security by allowing you to limit the scope of access granted to the service user.

Service users can be used in a variety of scenarios, including:

- **Automated scripts**: If you need to run automated scripts that access resources within your organization, you can use service users instead of storing your login credentials in plain text.
- **Third-party integrations**: If you want to integrate your resources 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.
- **Access control**: If you need to grant access to a specific set of resources to a particular application or service, you can create a service user with the necessary permissions.

### Creating a Service User

To create a service user, you'll need to log in to your organization's account and navigate to the "Service Users" section of your account settings.
<p align="center">
    <img src="/img/overview/service-user-overview.png" alt="service-user-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>

From there, you can create a new service user and specify the permissions that the user should have.

<p align="center">
    <img src="/img/overview/service-user-creation.png" alt="service-user-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>

<Note>
    It's important to keep your service users secure, as they can provide access to sensitive data and actions within your organization. You should treat your service users like you would treat your own personal account and limit the scope of access granted to the service user.
</Note>


## Personal Access Tokens

Personal access tokens are a type of authentication credential that allow you to access your account and perform actions on behalf of yourself or your organization.

### What are Personal Access Tokens used for?

Personal access tokens are typically used to authenticate API requests to a web service. They are an alternative to using your username and password, and can provide additional security by allowing you to limit the scope of access granted to the token.

Personal access tokens can be used in a variety of scenarios, including:

- **Automated scripts**: If you need to run automated scripts that access your account, you can use personal access tokens instead of storing your login credentials in plain text.
- **Third-party integrations**: If you want to integrate your account with a third-party service, you can use a personal access token to provide access to your data without giving the third-party service your login credentials.
- **Command-line tools**: If you use command-line tools to interact with your account, you can use personal access tokens to authenticate those requests.

### Creating a Personal Access Token

To create a personal access token, you'll need to log in to your account and navigate to the "Users" section and look for your user or create a [service user](#service-users) to use for your API requests.

<p align="center">
    <img src="/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>

From there, you can create a new token and specify the permissions that the token should have.

<p align="center">
    <img src="/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>

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.

<p align="center">
    <img src="/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>

<Note>
    It's important to keep your personal access tokens secure, as they can provide access to sensitive data and actions within your account. You should treat your personal access tokens like you would treat your password and never share them with anyone else.
</Note>

### Using Personal Access Tokens

Once you have created a personal access token, you can use it to authenticate requests to a web service that supports token-based authentication. To use a personal access token, you typically include it as an authentication header in your API requests.

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

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