Skip to main content
Setup keys are used to enroll new peers into your NetBird network without requiring interactive authentication. They’re ideal for automated deployments, IoT devices, and server installations.

​
List All Setup Keys

Returns a list of all setup keys. 
GET /api/setup-keys

curl -X GET https://api.netbird.io/api/setup-keys \
  -H "Authorization: Token nbp_YOUR_TOKEN"
​
id
string
Unique setup key identifier
​
key
string
Setup key as a masked secret (full key only shown on creation)
​
name
string
Setup key name identifier
​
expires
string
Expiration date (ISO 8601 format)
​
type
string
Key type: reusable or one-off
​
valid
boolean
Whether the key is currently valid
​
revoked
boolean
Whether the key has been revoked
​
used_times
integer
Number of times this key has been used
​
last_used
string
Last time the key was used (ISO 8601 format)
​
state
string
Key state: valid, overused, expired, or revoked
​
auto_groups
array
Group IDs to auto-assign to peers using this key
​
usage_limit
integer
Usage limit (0 = unlimited)
​
ephemeral
boolean
Whether peers enrolled with this key are ephemeral
​
allow_extra_dns_labels
boolean
Allow extra DNS labels to be added to the peer

​
Get a Setup Key

Retrieve details about a specific setup key. 
GET /api/setup-keys/{keyId}
​
keyId
string
required
The unique identifier of the setup key
Example
curl -X GET https://api.netbird.io/api/setup-keys/2531583362 \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Create a Setup Key

Generate a new setup key for peer enrollment. 
POST /api/setup-keys
​
name
string
required
Setup key name
​
type
string
required
Key type: reusable or one-off
​
expires_in
integer
required
Expiration time in seconds (86400-31536000, i.e., 1 day to 1 year)
​
auto_groups
array
required
Group IDs to auto-assign to peers registered with this key
​
usage_limit
integer
required
Usage limit (0 = unlimited)
​
ephemeral
boolean
required
Whether peers should be ephemeral
​
allow_extra_dns_labels
boolean
required
Allow extra DNS labels to be added to peers
curl -X POST https://api.netbird.io/api/setup-keys \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Servers",
    "type": "reusable",
    "expires_in": 2592000,
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "usage_limit": 0,
    "ephemeral": false,
    "allow_extra_dns_labels": false
  }'
The full setup key is only returned when created. Save it securely - you won’t be able to retrieve it again!

​
Update a Setup Key

Update setup key configuration. 
PUT /api/setup-keys/{keyId}
​
keyId
string
required
The unique identifier of the setup key
​
revoked
boolean
required
Revoke or un-revoke the setup key
​
auto_groups
array
required
Group IDs to auto-assign (replaces existing groups)
curl -X PUT https://api.netbird.io/api/setup-keys/2531583362 \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "revoked": true,
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"]
  }'

​
Delete a Setup Key

Permanently delete a setup key. 
DELETE /api/setup-keys/{keyId}
​
keyId
string
required
The unique identifier of the setup key
Example
curl -X DELETE https://api.netbird.io/api/setup-keys/2531583362 \
  -H "Authorization: Token nbp_YOUR_TOKEN"
Deleting a setup key does NOT remove peers that were enrolled with it. It only prevents future enrollments.

​
Key Types

​
Reusable Keys

Can be used multiple times until expired or revoked: 
{
  "type": "reusable",
  "usage_limit": 0
}
Use cases:
  • Server deployments
  • Container orchestration
  • IoT device fleets
  • Development environments

​
One-Off Keys

Can only be used once: 
{
  "type": "one-off",
  "usage_limit": 1
}
Use cases:
  • Individual device enrollment
  • Temporary access
  • High-security environments

​
Key States

Valid

Key is active and can be used

Expired

Key has passed its expiration date

Revoked

Key has been manually revoked

Overused

Key has exceeded its usage limit

​
Ephemeral Peers

Peers enrolled with ephemeral keys are automatically cleaned up: 
{
  "ephemeral": true
}
Ephemeral peers:
  • Automatically removed when disconnected
  • Don’t persist in the network
  • Ideal for temporary access or testing

​
Using Setup Keys

​
Linux/macOS

sudo netbird up --setup-key YOUR_SETUP_KEY

​
Windows

netbird up --setup-key YOUR_SETUP_KEY

​
Docker

docker run -d --name netbird \
  --network host \
  --cap-add NET_ADMIN \
  -e NB_SETUP_KEY=YOUR_SETUP_KEY \
  netbirdio/netbird:latest

​
Kubernetes

apiVersion: v1
kind: Secret
metadata:
  name: netbird-setup-key
type: Opaque
stringData:
  setup-key: YOUR_SETUP_KEY

​
Auto-Groups

Peers enrolled with a setup key are automatically added to specified groups: 
{
  "auto_groups": [
    "production-servers-group-id",
    "us-east-region-group-id"
  ]
}
This enables:
  • Automatic policy application
  • Simplified network segmentation
  • Role-based access control

​
Security Best Practices

Limit expiration - Use the shortest reasonable expiration period
Use one-off keys - For individual devices when possible
Set usage limits - Prevent unlimited use of reusable keys
Revoke unused keys - Regularly audit and revoke old keys
Rotate keys - Create new keys periodically for ongoing deployments
Secure storage - Store keys in secrets managers, not version control
Monitor usage - Track used_times and last_used to detect anomalies

​
Common Patterns

​
CI/CD Deployments

{
  "name": "CI/CD Pipeline",
  "type": "reusable",
  "expires_in": 604800,
  "usage_limit": 100,
  "auto_groups": ["ci-runners"],
  "ephemeral": true
}

​
IoT Devices

{
  "name": "IoT Sensors",
  "type": "reusable",
  "expires_in": 31536000,
  "usage_limit": 0,
  "auto_groups": ["iot-devices"],
  "ephemeral": false
}

​
Temporary Contractor Access

{
  "name": "Contractor - John Doe",
  "type": "one-off",
  "expires_in": 2592000,
  "usage_limit": 1,
  "auto_groups": ["contractors"],
  "ephemeral": false
}

Build docs developers (and LLMs) love

Get started for freeTalk to us