Setup Keys API

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": "2531583362",
    "key": "A6160****",
    "name": "Production Servers",
    "expires": "2024-06-01T14:47:22.291057Z",
    "type": "reusable",
    "valid": true,
    "revoked": false,
    "used_times": 5,
    "last_used": "2024-05-15T09:00:35.477782Z",
    "state": "valid",
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "updated_at": "2024-05-05T09:00:35.477782Z",
    "usage_limit": 0,
    "ephemeral": false,
    "allow_extra_dns_labels": false
  }
]

string

Unique setup key identifier

string

Setup key as a masked secret (full key only shown on creation)

string

Setup key name identifier

string

Expiration date (ISO 8601 format)

string

Key type: reusable or one-off

boolean

Whether the key is currently valid

boolean

Whether the key has been revoked

integer

Number of times this key has been used

string

Last time the key was used (ISO 8601 format)

string

Key state: valid, overused, expired, or revoked

array

Group IDs to auto-assign to peers using this key

integer

Usage limit (0 = unlimited)

boolean

Whether peers enrolled with this key are ephemeral

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}

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

string

required

Setup key name

string

required

Key type: reusable or one-off

integer

required

Expiration time in seconds (86400-31536000, i.e., 1 day to 1 year)

array

required

Group IDs to auto-assign to peers registered with this key

integer

required

Usage limit (0 = unlimited)

boolean

required

Whether peers should be ephemeral

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
  }'

curl -X POST https://api.netbird.io/api/setup-keys \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temporary Access",
    "type": "one-off",
    "expires_in": 86400,
    "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "usage_limit": 1,
    "ephemeral": true,
    "allow_extra_dns_labels": false
  }'

{
  "id": "2531583362",
  "key": "A616097E-FCF0-48FA-9354-CA4A61142761",
  "name": "Production Servers",
  "expires": "2024-07-01T14:47:22.291057Z",
  "type": "reusable",
  "valid": true,
  "revoked": false,
  "used_times": 0,
  "state": "valid",
  "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
  "updated_at": "2024-06-01T14:47:22.291057Z",
  "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}

string

required

The unique identifier of the setup key

boolean

required

Revoke or un-revoke the setup key

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"]
  }'

curl -X PUT https://api.netbird.io/api/setup-keys/2531583362 \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "revoked": false,
    "auto_groups": [
      "ch8i4ug6lnn4g9hqv7m0",
      "ch8i4ug6lnn4g9hqv7m1"
    ]
  }'

Delete a Setup Key

Permanently delete a setup key.

DELETE /api/setup-keys/{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
}

Getting Started

Resources

List All Setup Keys

Get a Setup Key

Create a Setup Key

Update a Setup Key

Delete a Setup Key

Key Types

Reusable Keys

One-Off Keys

Key States

Valid

Expired

Revoked

Overused

Ephemeral Peers

Using Setup Keys

Linux/macOS

Windows

Docker

Kubernetes

Auto-Groups

Security Best Practices

Common Patterns

CI/CD Deployments

IoT Devices

Temporary Contractor Access

​List All Setup Keys

​Get a Setup Key

​Create a Setup Key

​Update a Setup Key

​Delete a Setup Key

​Key Types

​Reusable Keys

​One-Off Keys

​Key States

Valid

Expired

Revoked

Overused

​Ephemeral Peers

​Using Setup Keys

​Linux/macOS

​Windows

​Docker

​Kubernetes

​Auto-Groups

​Security Best Practices

​Common Patterns

​CI/CD Deployments

​IoT Devices

​Temporary Contractor Access

List All Setup Keys

Get a Setup Key

Create a Setup Key

Update a Setup Key

Delete a Setup Key

Key Types

Reusable Keys

One-Off Keys

Key States

Ephemeral Peers

Using Setup Keys

Linux/macOS

Windows

Docker

Kubernetes

Auto-Groups

Security Best Practices

Common Patterns

CI/CD Deployments

IoT Devices

Temporary Contractor Access