POST/api/setup

Setup Instance

Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).

When the management server is started with NB_SETUP_PAT_ENABLED=true and the request includes create_pat: true, the endpoint also provisions the NetBird account for the new owner user and returns the plain text Personal Access Token in personal_access_token. The optional pat_expire_in value applies only when create_pat is true and defaults to 1 day when omitted. If a post-user step fails, setup-created resources are rolled back when safe; if account cleanup fails, the owner user is left in place to avoid leaving an account without its admin user.

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

5 body fields

Initial admin user details

create_patbooleanoptional

If true and the server has setup-time PAT issuance enabled (NB_SETUP_PAT_ENABLED=true), create a Personal Access Token for the new owner user and return it in the response. Ignored when the server feature is disabled.

emailstringrequired

Email address for the admin user

namestringrequired

Display name for the admin user (defaults to email if not provided)

passwordstringrequired

Password for the admin user (minimum 8 characters)

pat_expire_inintegeroptional

Expiration of the Personal Access Token in days. Applies only when create_pat is true and the server feature is enabled. Defaults to 1 day when omitted.

Default:1

4 status codes

200Setup completed successfully

emailstringrequired

Email address of the created user

personal_access_tokenstringoptional

Plain text Personal Access Token created during setup. Present only when create_pat was requested and the NB_SETUP_PAT_ENABLED feature was enabled on the server.

user_idstringrequired

The ID of the created user

400Bad Request

412Setup already completed

500Internal Server Error

Error handling

A 400 is returned: Bad Request. A 412 is returned: Setup already completed. A 500 is returned: Internal Server Error.

import { NetBirdManagementAPIUnofficialOctriFullPreview } from "netbird-read-only-mcp-preview-sdk";

const client = new NetBirdManagementAPIUnofficialOctriFullPreview({
  baseUrl: "https://api.netbird.io",
  auth: { bearerAuth: process.env.API_TOKEN! },
});

const result = await client.instance.createSetup({
  email: "admin@example.com",
  password: "securepassword123",
  name: "Admin User",
});

{
  "email": "admin@example.com",
  "personal_access_token": "nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "user_id": "abc123def456"
}

Request

Response

Errors