NetBird
NetBird access token setup: create a NetBird service user and expiring personal access token with the role needed to read or manage private DNS zones.
On this page
NetBird access token permissions
- Credential type
- Personal access token
- Preview access
- Service-user role: User (read-only access)
- Apply access
- Service-user role: Admin (write access)
- API endpoint
- You provide a public API endpoint.
Additional access
DNSControl id
{
"TYPE": "NETBIRD"
}Create credentials
Create a NetBird service user and expiring personal access token with the role needed to read or manage private DNS zones.
Access you'll grant
Service-user role: User (read-only access)
Service-user role: Admin (write access)
Before you start
- Permission to create service users in the NetBird account.
- At least one NetBird peer-group ID if DNSMigrator should create a custom DNS zone.
- For self-hosting, a public HTTPS management endpoint restricted to our egress IP; NetBird Cloud needs no customer endpoint.
Setup steps
0 of 5 done
Open Service Users
Sign in to the NetBird dashboard and open Team → Service Users. Use a non-interactive service user so automation does not depend on an employee account.
Create the service user
Create a service user with the User role for a read-only preview, or Admin when DNSMigrator must create zones and add, update, or delete records. Keep the role no broader than the workflow requires.
Create an expiring access token
Open the service user, create a personal access token, and choose a short practical expiration. Copy the plaintext token immediately: NetBird stores only its hash and cannot display the token again after the dialog closes.
Secure the self-hosted management URL
Skip this step for NetBird Cloud. For self-hosted NetBird, publish the management API on trusted HTTPS and allow
our egress IP. DNSMigrator calls over the public Internet. Its SSRF guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses, validates every DNS answer, and pins one validated IP. The URL may end at the origin or/api.Enter the token and zone defaults
Paste the secret into Personal access token. Leave Management URL empty for
https://api.netbird.io; otherwise enter the self-hosted HTTPS origin. If zones may be created, enter one or more IDs—not names—in Distribution group IDs, then check access.NetBird Cloud URLhttps://api.netbird.ioDistribution group IDsch8i4ug6lnn4g9hqv7m0, <second-group-id>
Troubleshooting
401 or “NetBird rejected the access token”
The PAT may be expired, revoked, or copied incompletely. Create a replacement on the service user and paste it immediately.
403 or DNS permission denied
Use a service user with User for preview or Admin for apply. Replacing the token does not change the role behind it.
A new zone cannot be created
Add at least one valid Distribution group ID. The API requires distribution_groups so NetBird knows which peers receive the zone.
A self-hosted URL is refused
Expose trusted HTTPS on a hostname whose entire DNS answer set is public and allow our egress IP; private and reserved addresses are intentionally blocked.
Official documentation
- NetBird: service users and access tokens
- NetBird API: DNS zones
- NetBird: self-hosted quickstart
- DNSControl: NetBird provider
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| Personal access tokentoken | Required | Plaintext PAT copied once from the service user. DNSMigrator sends it as Authorization: Token. |
| Management URLapiUrl | Optional | Leave empty for NetBird Cloud. For self-hosting, enter the public HTTPS management origin; a trailing /api is accepted. |
| Distribution group IDsdistributionGroups | Optional | Comma- or whitespace-separated NetBird group IDs whose peers should resolve newly created zones. Not needed for existing zones. |
Capabilities
- Create zones
- Yes
- List zones
- Yes
- DNSSEC
- Not available through this connection
- Minimum TTL
- 0 seconds
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
Caveats
- NetBird custom zones are private DNS served only to peers in the zone's distribution groups; creating a zone needs at least one distribution group ID.
- Only A, AAAA and CNAME records are supported.
- Self-hosted management servers are often on private networks: we only connect if the API is exposed publicly over HTTPS, because private and internal addresses are refused by design.
Troubleshooting
- 401 or “NetBird rejected the access token”
- The PAT may be expired, revoked, or copied incompletely. Create a replacement on the service user and paste it immediately.
- 403 or DNS permission denied
- Use a service user with User for preview or Admin for apply. Replacing the token does not change the role behind it.
- A new zone cannot be created
- Add at least one valid Distribution group ID. The API requires distribution_groups so NetBird knows which peers receive the zone.
- A self-hosted URL is refused
- Expose trusted HTTPS on a hostname whose entire DNS answer set is public and allow {egressIp}; private and reserved addresses are intentionally blocked.