A setup key is a pre-authentication token used to register machines in your EagleSafe ZTB network without requiring interactive SSO login. This enables automated, unattended deployments compatible with infrastructure-as-code tools such as Ansible, Terraform, and CloudFormation.
Register a machine with a setup key
netbird up --setup-key <SETUP_KEY>Types of setup keys
- One-off key — single use, authenticates one machine only. Recommended for security-sensitive deployments.
- Reusable key — can be used multiple times up to a configurable usage limit.
Ephemeral peers
When the ephemeral option is enabled on a setup key, peers registered with it are automatically removed from the network after being offline for more than 10 minutes. Useful for containers and autoscaling workloads.
Expiration and usage limit
Setup keys can have an expiration date and a usage limit. Once expired or the limit is reached, the key can no longer be used to register new machines. Machines already registered remain connected regardless.
Peer auto-grouping
When creating a setup key, you can assign one or more auto-assign groups. Every machine registered with that key is automatically added to those groups, and all access control rules for those groups apply immediately. Auto-grouping applies only to newly registered machines.
Create a setup key
- Go to Settings → Setup Keys and click Create Setup Key.
- Give the key a recognizable name, choose its type, set a usage limit, and assign auto-groups.
- Copy the key and store it in a secure location — it will not be shown again.
