[management] Align agent-network API contracts for API clients (#7026)

## Describe your changes

Work on the Terraform provider (terraform-provider-netbird #177–#183)
surfaced places where the agent-network API broke its own contracts or
deviated from the conventions the rest of the management API follows,
forcing client-side workarounds.

Settings reads now follow the settings-endpoint convention: GET always
answers with a JSON object. Before bootstrap it returns the defaults
with an empty cluster/subdomain/endpoint (previously 200 with a JSON
`null` body, while the spec said 404). The settings PUT can bootstrap
the account by carrying a `cluster` — previously the row could only come
into existence through the first provider create, and a settings-first
setup was impossible; a differing cluster on a bootstrapped account is
rejected instead of silently ignored. PUT remains full-state.

The provider PUT schema promised omit-preserves semantics for several
operator-editable fields that the handler never delivered (it builds the
row from the request, like every other update handler). The schema
wording now matches the shipped full-state behavior; only the api_key
(secret) and session keys stay preserved by the manager. Identity
headers are always present in provider responses so an explicitly
cleared value round-trips as an empty string.

The Go REST client gains the full agent-network surface (catalog,
providers, policies, guardrails, budget rules, settings), including a
shim translating the legacy 200+`null` settings body from older servers
into an `IsNotFound` error.

Note for reviewers: the dashboard special-cased the `null` settings
body; it needs a small follow-up for the new defaults response (in
progress).

management/internals/modules/agentnetwork/handlers/handlers_test.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
 	agentNetworkTypes "github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	"github.com/netbirdio/netbird/management/server/account"
 	nbcontext "github.com/netbirdio/netbird/management/server/context"
 	"github.com/netbirdio/netbird/management/server/permissions"
 	"github.com/netbirdio/netbird/management/server/store"
@@ -61,10 +62,23 @@ func newAgentNetworkHandlerFixture(t *testing.T) *agentNetworkHandlerFixture {
 		Return(true, context.Background(), nil).
 		AnyTimes()
 
-	manager := agentnetwork.NewManager(st, perms, nil, nil)
+	// Swallow activity events so the mutation paths (create/update/delete)
+	// are exercisable through the HTTP layer.
+	accounts := account.NewMockManager(ctrl)
+	accounts.EXPECT().
+		StoreEvent(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).
+		AnyTimes()
+	accounts.EXPECT().
+		UpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).
+		AnyTimes()
+
+	manager := agentnetwork.NewManager(st, perms, accounts, nil)
 	h := &handler{manager: manager}
 
 	router := mux.NewRouter()
+	router.HandleFunc("/agent-network/providers", h.createProvider).Methods("POST")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.getProvider).Methods("GET")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.updateProvider).Methods("PUT")
 	h.addPolicyEndpoints(router)
 	h.addConsumptionEndpoints(router)
 	h.addBudgetRuleEndpoints(router)

management/internals/modules/agentnetwork/handlers/providers_handler_test.go

@@ -1,7 +1,9 @@
 package handlers
 
 import (
+	"encoding/json"
 	"math"
+	nethttp "net/http"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -51,3 +53,50 @@ func TestValidate_ModelRates(t *testing.T) {
 		assert.Error(t, validate(base(m), true), "case %q must be rejected", name)
 	}
 }
+
+// TestProviderHandler_UpdateReplacesFullState pins the update contract shared
+// with the other PUT endpoints: the request replaces the provider's mutable
+// state, so optional fields absent from the JSON land as their zero values.
+// The two exceptions are server-side: the api_key (a secret — omitted means
+// "not rotated") and the session keypair, both preserved by the manager. The
+// identity headers stay on the wire as explicit empty strings so a cleared
+// value round-trips.
+func TestProviderHandler_UpdateReplacesFullState(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	create := `{
+        "provider_id": "openai_api",
+        "name": "openai",
+        "upstream_url": "https://api.openai.com",
+        "api_key": "sk-test",
+        "enabled": true,
+        "metadata_disabled": true,
+        "skip_tls_verification": true,
+        "extra_values": {"x-portkey-config": "pc-prod-3f2a"},
+        "identity_header_user_id": "x-bf-dim-netbird_user_id",
+        "models": [{"id": "gpt-4o", "input_per_1k": 0.0025, "output_per_1k": 0.01}]
+    }`
+	rec := f.do(t, nethttp.MethodPost, "/agent-network/providers", create)
+	require.Equal(t, nethttp.StatusOK, rec.Code, "create must succeed: %s", rec.Body.String())
+
+	var created api.AgentNetworkProvider
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &created))
+
+	// Minimal update: only the required fields, no api_key. Everything
+	// optional must land as its zero value.
+	update := `{"provider_id": "openai_api", "name": "openai-renamed", "upstream_url": "https://api.openai.com", "enabled": true}`
+	rec = f.do(t, nethttp.MethodPut, "/agent-network/providers/"+created.Id, update)
+	require.Equal(t, nethttp.StatusOK, rec.Code, "update without api_key must succeed (key is preserved): %s", rec.Body.String())
+
+	var updated api.AgentNetworkProvider
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &updated))
+	assert.Equal(t, "openai-renamed", updated.Name, "sent field must apply")
+	assert.True(t, updated.Enabled, "sent field must apply")
+	assert.False(t, updated.MetadataDisabled, "omitted metadata_disabled must land as false — PUT replaces the full state")
+	assert.False(t, updated.SkipTlsVerification, "omitted skip_tls_verification must land as false")
+	assert.Nil(t, updated.ExtraValues, "omitted extra_values must be cleared")
+	assert.Equal(t, "", updated.IdentityHeaderUserId, "omitted identity header must be cleared yet stay on the wire")
+	assert.Empty(t, updated.Models, "omitted models must be cleared")
+	assert.Contains(t, rec.Body.String(), `"identity_header_user_id":""`,
+		"cleared identity header must round-trip as an explicit empty string")
+}

management/internals/modules/agentnetwork/handlers/settings_handler.go

@@ -2,7 +2,6 @@ package handlers
 
 import (
 	"encoding/json"
-	"errors"
 	"net/http"
 
 	"github.com/gorilla/mux"
@@ -11,19 +10,20 @@ import (
 	nbcontext "github.com/netbirdio/netbird/management/server/context"
 	"github.com/netbirdio/netbird/shared/management/http/api"
 	"github.com/netbirdio/netbird/shared/management/http/util"
-	"github.com/netbirdio/netbird/shared/management/status"
 )
 
 // addSettingsEndpoints registers the Agent Network settings routes. The
-// settings row is bootstrapped server-side on first provider create; GET reads
-// it and PUT updates the mutable collection toggles (cluster/subdomain stay
-// immutable).
+// settings row is bootstrapped server-side on first provider create or on the
+// first PUT carrying a cluster; GET reads it and PUT applies a partial update
+// of the mutable collection toggles (cluster/subdomain stay immutable).
 func (h *handler) addSettingsEndpoints(router *mux.Router) {
 	router.HandleFunc("/agent-network/settings", h.getSettings).Methods("GET", "OPTIONS")
 	router.HandleFunc("/agent-network/settings", h.updateSettings).Methods("PUT", "OPTIONS")
 }
 
-// updateSettings applies the collection toggles to the account's settings row.
+// updateSettings replaces the mutable settings fields on the account's row.
+// A request carrying a cluster bootstraps the row when the account doesn't
+// have one yet.
 func (h *handler) updateSettings(w http.ResponseWriter, r *http.Request) {
 	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
 	if err != nil {
@@ -48,11 +48,9 @@ func (h *handler) updateSettings(w http.ResponseWriter, r *http.Request) {
 	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
 }
 
-// getSettings returns the account's agent-network settings. The settings
-// row is bootstrapped on first provider create, so freshly-onboarded
-// accounts have nothing to read. Rather than 404-ing in that case (which
-// the dashboard would have to special-case), return a JSON null with 200
-// so consumers can branch on the body alone.
+// getSettings returns the account's agent-network settings. Accounts that
+// haven't been bootstrapped yet read as the defaults with an empty cluster,
+// subdomain and endpoint; the manager synthesises that view.
 func (h *handler) getSettings(w http.ResponseWriter, r *http.Request) {
 	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
 	if err != nil {
@@ -62,11 +60,6 @@ func (h *handler) getSettings(w http.ResponseWriter, r *http.Request) {
 
 	settings, err := h.manager.GetSettings(r.Context(), userAuth.AccountId, userAuth.UserId)
 	if err != nil {
-		var sErr *status.Error
-		if errors.As(err, &sErr) && sErr.Type() == status.NotFound {
-			util.WriteJSONObject(r.Context(), w, nil)
-			return
-		}
 		util.WriteError(r.Context(), err, w)
 		return
 	}

management/internals/modules/agentnetwork/handlers/settings_handler_test.go

@@ -0,0 +1,137 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+// TestSettingsHandler_GetUnbootstrappedReturnsDefaults pins the settings-read
+// convention shared with the account and DNS settings endpoints: settings
+// always read as a JSON object. Before bootstrap that object carries the
+// defaults with an empty cluster/subdomain/endpoint (the "not bootstrapped"
+// signal) and no timestamps — never a 404 and never the legacy null body.
+func TestSettingsHandler_GetUnbootstrappedReturnsDefaults(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code,
+		"unbootstrapped account must read as 200 with defaults: got %d body=%s", rec.Code, rec.Body.String())
+	require.NotEqual(t, "null", trimSpace(rec.Body.String()),
+		"the legacy 200+null shape must not come back")
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Empty(t, got.Cluster, "cluster must be empty until bootstrapped")
+	assert.Empty(t, got.Subdomain, "subdomain must be empty until bootstrapped")
+	assert.Empty(t, got.Endpoint, "endpoint must be empty until bootstrapped, not a bare dot")
+	assert.True(t, got.EnableLogCollection, "defaults must show log collection on, matching bootstrap")
+	assert.False(t, got.EnablePromptCollection, "defaults must show prompt collection off")
+	assert.False(t, got.RedactPii, "defaults must show redaction off")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 30, *got.AccessLogRetentionDays, "defaults must show the bootstrap retention")
+	assert.Nil(t, got.CreatedAt, "no timestamps before a row exists")
+	assert.Nil(t, got.UpdatedAt, "no timestamps before a row exists")
+}
+
+// TestSettingsHandler_PutBootstrapsWithCluster covers the settings-first
+// bootstrap path: a PUT carrying a cluster on an unbootstrapped account
+// creates the row (cluster pinned, subdomain assigned) and applies the
+// mutable fields from the same request.
+func TestSettingsHandler_PutBootstrapsWithCluster(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": false, "access_log_retention_days": 30}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap PUT must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, "eu.proxy.netbird.io", got.Cluster, "cluster must be pinned from the request")
+	assert.NotEmpty(t, got.Subdomain, "subdomain must be assigned at bootstrap")
+	assert.Equal(t, got.Subdomain+".eu.proxy.netbird.io", got.Endpoint, "endpoint must combine subdomain and cluster")
+	assert.True(t, got.EnableLogCollection, "toggle from the bootstrap request must apply")
+	assert.True(t, got.EnablePromptCollection, "toggle from the bootstrap request must apply")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 30, *got.AccessLogRetentionDays, "retention from the bootstrap request must apply")
+
+	// The row is now readable via GET.
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code, "GET after bootstrap must succeed")
+}
+
+// TestSettingsHandler_PutWithoutClusterOnUnbootstrapped pins that a PUT
+// without a cluster cannot conjure a settings row out of nothing — there is
+// no cluster to pin — and surfaces as 404 like the GET.
+func TestSettingsHandler_PutWithoutClusterOnUnbootstrapped(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false}`)
+	assert.Equal(t, http.StatusNotFound, rec.Code,
+		"cluster-less PUT on an unbootstrapped account must 404: got %d body=%s", rec.Code, rec.Body.String())
+	assert.Contains(t, rec.Body.String(), "cluster",
+		"the error must point the caller at the bootstrap paths: %s", rec.Body.String())
+}
+
+// TestSettingsHandler_PutReplacesMutableFields pins the update contract shared
+// with the other PUT endpoints: the request replaces every mutable field, so a
+// toggle absent from the JSON lands as its zero value rather than being
+// preserved. Cluster and subdomain survive untouched.
+func TestSettingsHandler_PutReplacesMutableFields(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, "access_log_retention_days": 14}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap PUT must succeed: %s", rec.Body.String())
+
+	var before api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
+
+	rec = f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`)
+	require.Equal(t, http.StatusOK, rec.Code, "update PUT must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.True(t, got.EnableLogCollection, "sent toggle must apply")
+	assert.False(t, got.EnablePromptCollection, "sent toggle must apply")
+	assert.False(t, got.RedactPii, "sent toggle must apply")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 0, *got.AccessLogRetentionDays,
+		"retention absent from the request must land as the zero value — PUT replaces all mutable fields")
+	assert.Equal(t, before.Cluster, got.Cluster, "cluster must survive updates untouched")
+	assert.Equal(t, before.Subdomain, got.Subdomain, "subdomain must survive updates untouched")
+}
+
+// TestSettingsHandler_PutRejectsClusterChange pins cluster immutability: once
+// assigned, a differing cluster is rejected as a validation error instead of
+// being silently ignored, so callers never observe a value other than the one
+// they sent. Echoing the assigned cluster back stays valid, which lets
+// declarative clients send their full desired state idempotently.
+func TestSettingsHandler_PutRejectsClusterChange(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap PUT must succeed: %s", rec.Body.String())
+
+	rec = f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"cluster": "us.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"cluster change must be rejected as a validation error: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": true}`)
+	require.Equal(t, http.StatusOK, rec.Code, "echoing the assigned cluster must stay valid: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, "eu.proxy.netbird.io", got.Cluster, "cluster must be unchanged")
+	assert.True(t, got.RedactPii, "toggle sent alongside the echoed cluster must apply")
+}

management/internals/modules/agentnetwork/manager.go

@@ -207,7 +207,7 @@ func (m *managerImpl) CreateProvider(ctx context.Context, userID string, provide
 	}
 
 	if strings.TrimSpace(bootstrapCluster) != "" {
-		if _, err := m.bootstrapSettingsIfNeeded(ctx, provider.AccountID, bootstrapCluster); err != nil {
+		if _, err := m.bootstrapSettingsIfNeeded(ctx, m.store, provider.AccountID, bootstrapCluster); err != nil {
 			// The provider create has already succeeded; logging the
 			// bootstrap miss matches the plan's PoC behaviour. The synth
 			// path treats a missing settings row as a no-op, and the next
@@ -559,40 +559,83 @@ func (m *managerImpl) DeleteBudgetRule(ctx context.Context, accountID, userID, r
 	return nil
 }
 
-// UpdateSettings applies the mutable account-level settings — the collection
-// toggles — onto the existing row. Cluster and Subdomain are immutable and are
-// preserved from the persisted row regardless of the input. Because the
-// collection toggles change the synthesised service config (prompt-capture
-// gating, access-log emission), a reconcile is triggered so the proxy and peer
-// network maps converge on the new state.
+// UpdateSettings replaces the mutable account-level settings — the collection
+// toggles and retention — on the account's row. When the account has no
+// settings row yet, a non-empty settings.Cluster bootstraps one (same path as
+// first provider create); without it the update fails with NotFound. On an
+// existing row the cluster and subdomain are immutable: a differing
+// settings.Cluster is rejected rather than silently ignored so callers never
+// observe a value other than what they sent. Because the collection toggles
+// change the synthesised service config (prompt-capture gating, access-log
+// emission), a reconcile is triggered so the proxy and peer network maps
+// converge on the new state.
 func (m *managerImpl) UpdateSettings(ctx context.Context, userID string, settings *types.Settings) (*types.Settings, error) {
 	if err := m.requirePermission(ctx, settings.AccountID, userID, modules.AgentNetworkSettings, operations.Update); err != nil {
 		return nil, err
 	}
 
-	existing, err := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthUpdate, settings.AccountID)
+	requestedCluster := strings.TrimSpace(settings.Cluster)
+
+	// The row lock from LockingStrengthUpdate only holds for the duration of
+	// the surrounding transaction, so the read, the cluster-immutability
+	// check, and the save must share one — otherwise concurrent PUTs could
+	// interleave between them.
+	var updated *types.Settings
+	err := m.store.ExecuteInTransaction(ctx, func(tx store.Store) error {
+		existing, err := tx.GetAgentNetworkSettings(ctx, store.LockingStrengthUpdate, settings.AccountID)
+		switch {
+		case err == nil:
+			if requestedCluster != "" && requestedCluster != existing.Cluster {
+				return status.Errorf(status.InvalidArgument, "cluster is immutable once assigned (current: %s)", existing.Cluster)
+			}
+		case isNotFound(err):
+			if requestedCluster == "" {
+				return status.Errorf(status.NotFound, "agent network settings have not been bootstrapped yet; pass cluster to bootstrap them, or create a provider with bootstrap_cluster set")
+			}
+			// Bootstrapping pins the cluster and subdomain — a settings
+			// create on top of the update the caller already passed, matching
+			// the gate on the provider-create bootstrap path.
+			if err := m.requirePermission(ctx, settings.AccountID, userID, modules.AgentNetworkSettings, operations.Create); err != nil {
+				return err
+			}
+			existing, err = m.bootstrapSettingsIfNeeded(ctx, tx, settings.AccountID, requestedCluster)
+			if err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("get agent network settings: %w", err)
+		}
+
+		existing.EnableLogCollection = settings.EnableLogCollection
+		existing.EnablePromptCollection = settings.EnablePromptCollection
+		existing.RedactPii = settings.RedactPii
+		existing.AccessLogRetentionDays = settings.AccessLogRetentionDays
+		existing.UpdatedAt = time.Now().UTC()
+
+		if err := tx.SaveAgentNetworkSettings(ctx, existing); err != nil {
+			return fmt.Errorf("save agent network settings: %w", err)
+		}
+		updated = existing
+		return nil
+	})
 	if err != nil {
-		return nil, fmt.Errorf("get agent network settings: %w", err)
-	}
-
-	existing.EnableLogCollection = settings.EnableLogCollection
-	existing.EnablePromptCollection = settings.EnablePromptCollection
-	existing.RedactPii = settings.RedactPii
-	existing.AccessLogRetentionDays = settings.AccessLogRetentionDays
-	existing.UpdatedAt = time.Now().UTC()
-
-	if err := m.store.SaveAgentNetworkSettings(ctx, existing); err != nil {
-		return nil, fmt.Errorf("save agent network settings: %w", err)
+		return nil, err
 	}
 
 	m.accountManager.StoreEvent(ctx, userID, settings.AccountID, settings.AccountID, activity.AgentNetworkSettingsUpdated, map[string]any{
-		"log_collection":    existing.EnableLogCollection,
-		"prompt_collection": existing.EnablePromptCollection,
-		"redact_pii":        existing.RedactPii,
+		"log_collection":    updated.EnableLogCollection,
+		"prompt_collection": updated.EnablePromptCollection,
+		"redact_pii":        updated.RedactPii,
 	})
 	m.reconcile(ctx, settings.AccountID)
 
-	return existing, nil
+	return updated, nil
+}
+
+// isNotFound reports whether err is a status.NotFound error.
+func isNotFound(err error) bool {
+	var sErr *status.Error
+	return errors.As(err, &sErr) && sErr.Type() == status.NotFound
 }
 
 // validateProviderRefs ensures every destination provider id refers to a
@@ -616,22 +659,25 @@ func (m *managerImpl) validateProviderRefs(ctx context.Context, accountID string
 	return nil
 }
 
-// GetSettings returns the agent-network settings row for the account.
-// Returns the underlying status.NotFound when no row has been
-// bootstrapped yet (i.e. the account has no providers).
+// GetSettings returns the agent-network settings row for the account. When no
+// row has been bootstrapped yet, the defaults are returned (without
+// persisting) with cluster and subdomain empty — settings always read as an
+// object, like the account and DNS settings endpoints.
 func (m *managerImpl) GetSettings(ctx context.Context, accountID, userID string) (*types.Settings, error) {
 	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkSettings, operations.Read); err != nil {
 		return nil, err
 	}
-	return m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
+	settings, err := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
+	switch {
+	case err == nil:
+		return settings, nil
+	case isNotFound(err):
+		return types.DefaultSettings(accountID), nil
+	default:
+		return nil, err
+	}
 }
 
-// bootstrapSettingsIfNeeded creates the per-account agent-network
-// settings row when missing. The cluster comes from the create-time
-// hint the dashboard sends (auto-picked from the active cluster list);
-// the subdomain is picked from the curated wordlist avoiding
-// collisions on the same cluster. Idempotent: if a row already exists
-// it is returned untouched and the hint is ignored.
 // requireSettingsBootstrapPermission gates the one-time settings bootstrap a
 // first provider create performs. Pinning the account's cluster and subdomain
 // is a settings write, so it needs the settings permission on top of the
@@ -641,14 +687,20 @@ func (m *managerImpl) requireSettingsBootstrapPermission(ctx context.Context, ac
 	if err == nil {
 		return nil
 	}
-	var sErr *status.Error
-	if !errors.As(err, &sErr) || sErr.Type() != status.NotFound {
+	if !isNotFound(err) {
 		return fmt.Errorf("get agent network settings: %w", err)
 	}
 	return m.requirePermission(ctx, accountID, userID, modules.AgentNetworkSettings, operations.Create)
 }
 
-func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, accountID, providerCluster string) (*types.Settings, error) {
+// bootstrapSettingsIfNeeded creates the per-account agent-network
+// settings row when missing. The cluster comes from the create-time
+// hint the dashboard sends (auto-picked from the active cluster list);
+// the subdomain is picked from the curated wordlist avoiding
+// collisions on the same cluster. Idempotent: if a row already exists
+// it is returned untouched and the hint is ignored. st is the store to
+// operate on — pass the transaction store when calling from within one.
+func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, st store.Store, accountID, providerCluster string) (*types.Settings, error) {
 	if accountID == "" {
 		return nil, fmt.Errorf("bootstrap settings: account id is required")
 	}
@@ -656,16 +708,15 @@ func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, accountID,
 		return nil, fmt.Errorf("bootstrap settings: provider cluster is required")
 	}
 
-	existing, err := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
+	existing, err := st.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
 	if err == nil {
 		return existing, nil
 	}
-	var sErr *status.Error
-	if !errors.As(err, &sErr) || sErr.Type() != status.NotFound {
+	if !isNotFound(err) {
 		return nil, fmt.Errorf("get agent network settings: %w", err)
 	}
 
-	siblings, err := m.store.GetAgentNetworkSettingsByCluster(ctx, store.LockingStrengthNone, providerCluster)
+	siblings, err := st.GetAgentNetworkSettingsByCluster(ctx, store.LockingStrengthNone, providerCluster)
 	if err != nil {
 		return nil, fmt.Errorf("list agent network settings on cluster: %w", err)
 	}
@@ -684,18 +735,12 @@ func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, accountID,
 	m.labelRngMu.Unlock()
 
 	now := time.Now().UTC()
-	settings := &types.Settings{
-		AccountID: accountID,
-		Cluster:   providerCluster,
-		Subdomain: subdomain,
-		// Logs on by default; usage is collected regardless. Retention bounds
-		// how long full log rows are kept.
-		EnableLogCollection:    true,
-		AccessLogRetentionDays: types.DefaultAccessLogRetentionDays,
-		CreatedAt:              now,
-		UpdatedAt:              now,
-	}
-	if err := m.store.SaveAgentNetworkSettings(ctx, settings); err != nil {
+	settings := types.DefaultSettings(accountID)
+	settings.Cluster = providerCluster
+	settings.Subdomain = subdomain
+	settings.CreatedAt = now
+	settings.UpdatedAt = now
+	if err := st.SaveAgentNetworkSettings(ctx, settings); err != nil {
 		return nil, fmt.Errorf("save agent network settings: %w", err)
 	}
 	return settings, nil
@@ -898,8 +943,8 @@ func (*mockManager) UpdateBudgetRule(_ context.Context, _ string, r *types.Accou
 
 func (*mockManager) DeleteBudgetRule(_ context.Context, _, _, _ string) error { return nil }
 
-func (*mockManager) GetSettings(_ context.Context, _, _ string) (*types.Settings, error) {
-	return nil, status.Errorf(status.NotFound, "agent network settings not found")
+func (*mockManager) GetSettings(_ context.Context, accountID, _ string) (*types.Settings, error) {
+	return types.DefaultSettings(accountID), nil
 }
 
 func (*mockManager) UpdateSettings(_ context.Context, _ string, s *types.Settings) (*types.Settings, error) {

management/internals/modules/agentnetwork/types/provider.go

@@ -164,9 +164,7 @@ func (p *Provider) FromAPIRequest(req *api.AgentNetworkProviderRequest) {
 		p.MetadataDisabled = *req.MetadataDisabled
 	}
 	// Identity-header overrides for catalogs flagged Customizable.
-	// nil pointer = "field omitted on the wire" → leave the stored
-	// value untouched (per the openapi description). Empty string is
-	// an explicit clear that disables stamping for this dimension.
+	// Empty or omitted disables stamping for this dimension.
 	if req.IdentityHeaderUserId != nil {
 		p.IdentityHeaderUserID = strings.TrimSpace(*req.IdentityHeaderUserId)
 	}
@@ -192,16 +190,20 @@ func (p *Provider) ToAPIResponse() *api.AgentNetworkProvider {
 	created := p.CreatedAt
 	updated := p.UpdatedAt
 	resp := &api.AgentNetworkProvider{
-		Id:                  p.ID,
-		ProviderId:          p.ProviderID,
-		Name:                p.Name,
-		UpstreamUrl:         p.UpstreamURL,
-		Models:              models,
-		Enabled:             p.Enabled,
-		SkipTlsVerification: p.SkipTLSVerification,
-		MetadataDisabled:    p.MetadataDisabled,
-		CreatedAt:           &created,
-		UpdatedAt:           &updated,
+		Id:          p.ID,
+		ProviderId:  p.ProviderID,
+		Name:        p.Name,
+		UpstreamUrl: p.UpstreamURL,
+		Models:      models,
+		// Always present on the wire so an explicitly cleared header
+		// round-trips as "" instead of vanishing from the response.
+		IdentityHeaderUserId: p.IdentityHeaderUserID,
+		IdentityHeaderGroups: p.IdentityHeaderGroups,
+		Enabled:              p.Enabled,
+		SkipTlsVerification:  p.SkipTLSVerification,
+		MetadataDisabled:     p.MetadataDisabled,
+		CreatedAt:            &created,
+		UpdatedAt:            &updated,
 	}
 	if len(p.ExtraValues) > 0 {
 		out := make(map[string]string, len(p.ExtraValues))
@@ -210,14 +212,6 @@ func (p *Provider) ToAPIResponse() *api.AgentNetworkProvider {
 		}
 		resp.ExtraValues = &out
 	}
-	if p.IdentityHeaderUserID != "" {
-		v := p.IdentityHeaderUserID
-		resp.IdentityHeaderUserId = &v
-	}
-	if p.IdentityHeaderGroups != "" {
-		v := p.IdentityHeaderGroups
-		resp.IdentityHeaderGroups = &v
-	}
 	return resp
 }
 

management/internals/modules/agentnetwork/types/provider_test.go

@@ -77,3 +77,41 @@ func TestProvider_MetadataDisabled_RoundTrip(t *testing.T) {
 	assert.False(t, p.MetadataDisabled, "explicit false must clear metadata_disabled")
 	assert.False(t, p.ToAPIResponse().MetadataDisabled, "response must reflect the cleared value")
 }
+
+// TestProvider_IdentityHeaders_AlwaysOnWire pins that the identity header
+// fields are always present in the API response — an explicitly cleared
+// ("") header must round-trip as "" rather than vanish, so API consumers
+// (e.g. the Terraform provider) never observe a value other than the one
+// they wrote.
+func TestProvider_IdentityHeaders_AlwaysOnWire(t *testing.T) {
+	set := "x-bf-dim-netbird_user_id"
+	empty := ""
+
+	base := func() *api.AgentNetworkProviderRequest {
+		return &api.AgentNetworkProviderRequest{
+			ProviderId:  "custom",
+			Name:        "bifrost",
+			UpstreamUrl: "https://bifrost.internal",
+		}
+	}
+
+	p := NewProvider("acc-1")
+	resp := p.ToAPIResponse()
+	assert.Equal(t, "", resp.IdentityHeaderUserId, "unset header must surface as empty string, not be omitted")
+	assert.Equal(t, "", resp.IdentityHeaderGroups, "unset header must surface as empty string, not be omitted")
+
+	req := base()
+	req.IdentityHeaderUserId = &set
+	p.FromAPIRequest(req)
+	assert.Equal(t, set, p.ToAPIResponse().IdentityHeaderUserId, "configured header must round-trip")
+
+	// Omitting the field preserves it.
+	p.FromAPIRequest(base())
+	assert.Equal(t, set, p.ToAPIResponse().IdentityHeaderUserId, "omitted header must preserve the stored value")
+
+	// An explicit "" clears it AND stays visible on the wire.
+	req = base()
+	req.IdentityHeaderUserId = &empty
+	p.FromAPIRequest(req)
+	assert.Equal(t, "", p.ToAPIResponse().IdentityHeaderUserId, "cleared header must round-trip as empty string")
+}

management/internals/modules/agentnetwork/types/settings.go

@@ -1,6 +1,7 @@
 package types
 
 import (
+	"strings"
 	"time"
 
 	"github.com/netbirdio/netbird/shared/management/http/api"
@@ -42,18 +43,34 @@ type Settings struct {
 // schema cohesive.
 func (Settings) TableName() string { return "agent_network_settings" }
 
+// DefaultSettings returns the settings an account observes before its row is
+// bootstrapped: log collection on with the default retention, everything else
+// off, and no cluster/subdomain assigned yet. Bootstrap persists exactly these
+// values plus the assigned cluster and subdomain, so the pre-bootstrap read
+// and the freshly bootstrapped row agree.
+func DefaultSettings(accountID string) *Settings {
+	return &Settings{
+		AccountID:              accountID,
+		EnableLogCollection:    true,
+		AccessLogRetentionDays: DefaultAccessLogRetentionDays,
+	}
+}
+
 // Endpoint returns the bare hostname agents reach this account at:
-// `<subdomain>.<cluster>`.
+// `<subdomain>.<cluster>`. Empty until both halves are assigned at bootstrap.
 func (s *Settings) Endpoint() string {
+	if s.Cluster == "" || s.Subdomain == "" {
+		return ""
+	}
 	return s.Subdomain + "." + s.Cluster
 }
 
-// ToAPIResponse renders the settings as the API representation.
+// ToAPIResponse renders the settings as the API representation. The
+// timestamps are omitted while zero — a default (not yet bootstrapped) view
+// has no persisted row to date.
 func (s *Settings) ToAPIResponse() *api.AgentNetworkSettings {
-	created := s.CreatedAt
-	updated := s.UpdatedAt
 	retention := s.AccessLogRetentionDays
-	return &api.AgentNetworkSettings{
+	resp := &api.AgentNetworkSettings{
 		Cluster:                s.Cluster,
 		Subdomain:              s.Subdomain,
 		Endpoint:               s.Endpoint(),
@@ -61,14 +78,27 @@ func (s *Settings) ToAPIResponse() *api.AgentNetworkSettings {
 		EnablePromptCollection: s.EnablePromptCollection,
 		RedactPii:              s.RedactPii,
 		AccessLogRetentionDays: &retention,
-		CreatedAt:              &created,
-		UpdatedAt:              &updated,
 	}
+	if !s.CreatedAt.IsZero() {
+		created := s.CreatedAt
+		resp.CreatedAt = &created
+	}
+	if !s.UpdatedAt.IsZero() {
+		updated := s.UpdatedAt
+		resp.UpdatedAt = &updated
+	}
+	return resp
 }
 
-// FromAPIRequest applies the mutable settings fields from the request. Cluster
-// and Subdomain are immutable and intentionally not touched here.
+// FromAPIRequest applies the request onto the receiver. The mutable
+// collection fields are always replaced with the request values. Cluster
+// participates only in bootstrap and the immutability check (see
+// Manager.UpdateSettings); Subdomain is server-assigned and never taken
+// from a request.
 func (s *Settings) FromAPIRequest(req *api.AgentNetworkSettingsRequest) {
+	if req.Cluster != nil {
+		s.Cluster = strings.TrimSpace(*req.Cluster)
+	}
 	s.EnableLogCollection = req.EnableLogCollection
 	s.EnablePromptCollection = req.EnablePromptCollection
 	s.RedactPii = req.RedactPii