Skip to main content
The NetBird API supports two authentication methods:
  1. Personal Access Tokens (recommended for API access)
  2. 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

1

Navigate to Settings

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

Generate Token

Click Create Token and provide:
  • Name: A descriptive name for the token
  • Expiration: Token validity period (1-365 days)
3

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"

​
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
​
userId
string
required
The unique identifier of the user
​
name
string
required
Name of the token
​
expires_in
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
  }'
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"
​
id
string
Token ID
​
name
string
Token name
​
expiration_date
string
When the token expires (ISO 8601 format)
​
last_used
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

​
401 Unauthorized
Missing or invalid authentication credentials
{
  "message": "unauthorized"
}
​
403 Forbidden
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

Build docs developers (and LLMs) love

Get started for freeTalk to us