NetBird Read-Only MCP Preview
POST/api/setup-keys

Create a setup key

Creates a setup key for registering peers. Provide its name, type, expires_in, auto_groups, and usage_limit to configure the key's lifespan, assignments, and usage.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

7 body fields

Setup key settings. If you submit a body, include name, type, expires_in, auto_groups, and usage_limit.

allow_extra_dns_labelsbooleanoptional
Allow extra DNS labels to be added to the peer
auto_groupsarray<string>required
List of group IDs to auto-assign to peers registered with this key
ephemeralbooleanoptional
Indicate that the peer will be ephemeral or not
expires_inintegerrequired
Expiration time in seconds
namestringrequired
Setup Key name
typestringrequired
Setup key type, one-off for single time usage and reusable
usage_limitintegerrequired
A number of times this key can be used. The value of 0 indicates the unlimited usage.

5 status codes
200Returns the created setup key object, including its key value and configuration.
allow_extra_dns_labelsbooleanrequired
Allow extra DNS labels to be added to the peer
auto_groupsarray<string>required
List of group IDs to auto-assign to peers registered with this key
ephemeralbooleanrequired
Indicate that the peer will be ephemeral or not
expiresstringrequired
Setup Key expiration date
idstringrequired
Setup Key ID
last_usedstringrequired
Setup key last usage date
namestringrequired
Setup key name identifier
revokedbooleanrequired
Setup key revocation status
statestringrequired
Setup key status, "valid", "overused","expired" or "revoked"
typestringrequired
Setup key type, one-off for single time usage and reusable
updated_atstringrequired
Setup key last update date
usage_limitintegerrequired
A number of times this key can be used. The value of 0 indicates the unlimited usage.
used_timesintegerrequired
Usage count of setup key
validbooleanrequired
Setup key validity status
keystringrequired
Setup Key as plain text
400Returned when the request is invalid.
401Returned when the request lacks required authentication.
403Returned when the request is forbidden.
500Returned when an internal server error occurs.

Error handling

A 400 indicates invalid request data, a 401 indicates missing authentication, a 403 indicates insufficient permission, and a 500 indicates an internal server error. A submitted body must include name, type, expires_in, auto_groups, and usage_limit; expires_in must be between 86400 and 31536000 seconds.