Authentication

The NetBird API supports two authentication methods:

Personal Access Tokens (recommended for API access)
Bearer Tokens (JWT) (used for dashboard authentication)

Personal Access Tokens

Personal Access Tokens (PATs) are the recommended way to authenticate API requests. They provide secure, long-lived credentials for programmatic access.

Creating a Personal Access Token

Navigate to Settings

In the NetBird dashboard, go to Settings > Personal Access Tokens

Generate Token

Click Create Token and provide:

Name: A descriptive name for the token
Expiration: Token validity period (1-365 days)

Save Token

Copy the token immediately - it won’t be shown again!

Using the Token

Include the token in the Authorization header with the Token prefix:

curl -X GET https://api.netbird.io/api/users \
  -H "Authorization: Token nbp_1234567890abcdef..."

curl -X GET https://api.netbird.io/api/users \
  -H "Authorization: Token nbp_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

import requests

token = "nbp_YOUR_TOKEN_HERE"
headers = {
    "Authorization": f"Token {token}",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.netbird.io/api/users",
    headers=headers
)

const token = 'nbp_YOUR_TOKEN_HERE';

const response = await fetch('https://api.netbird.io/api/users', {
  headers: {
    'Authorization': `Token ${token}`,
    'Content-Type': 'application/json'
  }
});

package main

import (
    "net/http"
)

func main() {
    token := "nbp_YOUR_TOKEN_HERE"
    
    req, _ := http.NewRequest("GET", "https://api.netbird.io/api/users", nil)
    req.Header.Set("Authorization", "Token "+token)
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Managing Tokens via API

Create a Personal Access Token

You need to be authenticated (with an existing token or JWT) to create new tokens programmatically.

Create Token

POST /api/users/{userId}/tokens

string

required

The unique identifier of the user

string

required

Name of the token

integer

required

Expiration time in days (1-365)

curl -X POST https://api.netbird.io/api/users/google-oauth2|123456/tokens \
  -H "Authorization: Token nbp_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Token",
    "expires_in": 90
  }'

{
  "plain_token": "nbp_abc123def456...",
  "personal_access_token": {
    "id": "ch8i54g6lnn4g9hqv7n0",
    "name": "CI/CD Token",
    "expiration_date": "2024-06-15T14:38:28.977616Z",
    "created_by": "google-oauth2|123456",
    "created_at": "2024-03-15T14:48:20.465209Z"
  }
}

The plain_token is only returned once when the token is created. Store it securely!

List Personal Access Tokens

List Tokens

GET /api/users/{userId}/tokens

Example

curl -X GET https://api.netbird.io/api/users/google-oauth2|123456/tokens \
  -H "Authorization: Token nbp_YOUR_TOKEN"

string

Token ID

string

Token name

string

When the token expires (ISO 8601 format)

string

Last time the token was used (ISO 8601 format)

Delete a Personal Access Token

Delete Token

DELETE /api/users/{userId}/tokens/{tokenId}

Example

curl -X DELETE https://api.netbird.io/api/users/google-oauth2|123456/tokens/ch8i54g6lnn4g9hqv7n0 \
  -H "Authorization: Token nbp_YOUR_TOKEN"

Bearer Token (JWT)

Bearer tokens are JWT tokens obtained through OAuth2 authentication flow. They’re primarily used by the NetBird dashboard.

Using Bearer Tokens

Include the JWT in the Authorization header with the Bearer prefix:

curl -X GET https://api.netbird.io/api/users \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Authentication Errors

Missing or invalid authentication credentials

{
  "message": "unauthorized"
}

Authenticated but insufficient permissions

{
  "message": "forbidden"
}

Best Practices

Rotate tokens regularly - Set appropriate expiration periods and rotate tokens before they expire

Use minimal permissions - Create service users with limited roles for automation

Store securely - Never commit tokens to version control; use environment variables or secret managers

Monitor usage - Check the last_used field to identify unused tokens

Revoke compromised tokens - Immediately delete any tokens that may be compromised

Getting Started

Resources

Personal Access Tokens

Creating a Personal Access Token

Using the Token

Managing Tokens via API

Create a Personal Access Token

List Personal Access Tokens

Delete a Personal Access Token

Bearer Token (JWT)

Using Bearer Tokens

Authentication Errors

Best Practices

​Personal Access Tokens

​Creating a Personal Access Token

​Using the Token

​Managing Tokens via API

​Create a Personal Access Token

​List Personal Access Tokens

​Delete a Personal Access Token

​Bearer Token (JWT)

​Using Bearer Tokens

​Authentication Errors

​Best Practices

Personal Access Tokens

Creating a Personal Access Token

Using the Token

Managing Tokens via API

Create a Personal Access Token

List Personal Access Tokens

Delete a Personal Access Token

Bearer Token (JWT)

Using Bearer Tokens

Authentication Errors

Best Practices