feat: add bulk user secret import endpoint and SDK client (PLAT-240) (#26724)

Adds `POST /api/v2/users/{user}/secrets/batch` and
`codersdk.Client.ImportUserSecrets` to import env, JSON, or YAML secrets
atomically. The endpoint validates each entry, rolls back the full batch
on conflicts or limits, omits secret values from responses and audit
logs, and imports keys that cannot be injected as environment variables
with an empty `env_name`.

Part of the [PLAT-240 bulk secret import
stack](https://linear.app/codercom/issue/PLAT-240). Reviewed and updated
by Coder Agents on behalf of @dylanhuff-at-coder.

coderd/apidoc/docs.go

@@ -11027,6 +11027,73 @@ const docTemplate = `{
                 ]
             }
         },
+        "/api/v2/users/{user}/secrets/batch": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Secrets"
+                ],
+                "summary": "Import user secrets from a file",
+                "operationId": "import-user-secrets-from-a-file",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User ID, username, or me",
+                        "name": "user",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Import secrets request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.ImportUserSecretsRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/codersdk.UserSecret"
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.Response"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.Response"
+                        }
+                    },
+                    "413": {
+                        "description": "Request Entity Too Large",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.Response"
+                        }
+                    }
+                },
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ]
+            }
+        },
         "/api/v2/users/{user}/secrets/{name}": {
             "get": {
                 "produces": [
@@ -20578,6 +20645,21 @@ const docTemplate = `{
                 }
             }
         },
+        "codersdk.ImportUserSecretsRequest": {
+            "type": "object",
+            "required": [
+                "content",
+                "format"
+            ],
+            "properties": {
+                "content": {
+                    "type": "string"
+                },
+                "format": {
+                    "$ref": "#/definitions/codersdk.SecretsFileFormat"
+                }
+            }
+        },
         "codersdk.InboxNotification": {
             "type": "object",
             "properties": {
@@ -23647,6 +23729,19 @@ const docTemplate = `{
                 }
             }
         },
+        "codersdk.SecretsFileFormat": {
+            "type": "string",
+            "enum": [
+                "env",
+                "json",
+                "yaml"
+            ],
+            "x-enum-varnames": [
+                "SecretsFileFormatEnv",
+                "SecretsFileFormatJSON",
+                "SecretsFileFormatYAML"
+            ]
+        },
         "codersdk.ServerSentEvent": {
             "type": "object",
             "properties": {

coderd/apidoc/swagger.json

@@ -9780,6 +9780,67 @@
 				]
 			}
 		},
+		"/api/v2/users/{user}/secrets/batch": {
+			"post": {
+				"consumes": ["application/json"],
+				"produces": ["application/json"],
+				"tags": ["Secrets"],
+				"summary": "Import user secrets from a file",
+				"operationId": "import-user-secrets-from-a-file",
+				"parameters": [
+					{
+						"type": "string",
+						"description": "User ID, username, or me",
+						"name": "user",
+						"in": "path",
+						"required": true
+					},
+					{
+						"description": "Import secrets request",
+						"name": "request",
+						"in": "body",
+						"required": true,
+						"schema": {
+							"$ref": "#/definitions/codersdk.ImportUserSecretsRequest"
+						}
+					}
+				],
+				"responses": {
+					"201": {
+						"description": "Created",
+						"schema": {
+							"type": "array",
+							"items": {
+								"$ref": "#/definitions/codersdk.UserSecret"
+							}
+						}
+					},
+					"400": {
+						"description": "Bad Request",
+						"schema": {
+							"$ref": "#/definitions/codersdk.Response"
+						}
+					},
+					"409": {
+						"description": "Conflict",
+						"schema": {
+							"$ref": "#/definitions/codersdk.Response"
+						}
+					},
+					"413": {
+						"description": "Request Entity Too Large",
+						"schema": {
+							"$ref": "#/definitions/codersdk.Response"
+						}
+					}
+				},
+				"security": [
+					{
+						"CoderSessionToken": []
+					}
+				]
+			}
+		},
 		"/api/v2/users/{user}/secrets/{name}": {
 			"get": {
 				"produces": ["application/json"],
@@ -18738,6 +18799,18 @@
 				}
 			}
 		},
+		"codersdk.ImportUserSecretsRequest": {
+			"type": "object",
+			"required": ["content", "format"],
+			"properties": {
+				"content": {
+					"type": "string"
+				},
+				"format": {
+					"$ref": "#/definitions/codersdk.SecretsFileFormat"
+				}
+			}
+		},
 		"codersdk.InboxNotification": {
 			"type": "object",
 			"properties": {
@@ -21682,6 +21755,15 @@
 				}
 			}
 		},
+		"codersdk.SecretsFileFormat": {
+			"type": "string",
+			"enum": ["env", "json", "yaml"],
+			"x-enum-varnames": [
+				"SecretsFileFormatEnv",
+				"SecretsFileFormatJSON",
+				"SecretsFileFormatYAML"
+			]
+		},
 		"codersdk.ServerSentEvent": {
 			"type": "object",
 			"properties": {

coderd/coderd.go

@@ -1816,6 +1816,7 @@ func New(options *Options) *API {
 						r.Put("/gitsshkey", api.regenerateGitSSHKey)
 						r.Route("/secrets", func(r chi.Router) {
 							r.Post("/", api.postUserSecret)
+							r.Post("/batch", api.postUserSecretsBatch)
 							r.Get("/", api.getUserSecrets)
 							r.Route("/{name}", func(r chi.Router) {
 								r.Get("/", api.getUserSecret)

coderd/httpapi/httpapi.go

@@ -239,6 +239,13 @@ func Read(ctx context.Context, rw http.ResponseWriter, r *http.Request, value in
 
 	err := json.NewDecoder(r.Body).Decode(value)
 	if err != nil {
+		if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
+			Write(ctx, rw, http.StatusRequestEntityTooLarge, codersdk.Response{
+				Message: "Request body too large.",
+				Detail:  err.Error(),
+			})
+			return false
+		}
 		Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
 			Message: "Request body must be valid JSON.",
 			Detail:  err.Error(),

coderd/httpapi/httpapi_test.go

@@ -96,6 +96,17 @@ func TestRead(t *testing.T) {
 		require.False(t, httpapi.Read(ctx, rw, r, v))
 	})
 
+	t.Run("BodyTooLarge", func(t *testing.T) {
+		t.Parallel()
+		ctx := context.Background()
+		rw := httptest.NewRecorder()
+		r := httptest.NewRequest("POST", "/", strings.NewReader(`{"value":"too large"}`))
+		r.Body = http.MaxBytesReader(rw, r.Body, 4)
+		var v json.RawMessage
+		require.False(t, httpapi.Read(ctx, rw, r, &v))
+		require.Equal(t, http.StatusRequestEntityTooLarge, rw.Code)
+	})
+
 	t.Run("Validate", func(t *testing.T) {
 		t.Parallel()
 		type toValidate struct {

coderd/usersecrets.go

@@ -81,6 +81,10 @@ func (api *API) postUserSecret(rw http.ResponseWriter, r *http.Request) {
 			httpapi.Write(ctx, rw, http.StatusBadRequest, resp)
 			return
 		}
+		if httpapi.IsUnauthorizedError(err) {
+			httpapi.Forbidden(rw)
+			return
+		}
 		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
 			Message: "Internal error creating secret.",
 			Detail:  err.Error(),
@@ -92,6 +96,141 @@ func (api *API) postUserSecret(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusCreated, db2sdk.UserSecretFromFull(secret))
 }
 
+// @Summary Import user secrets from a file
+// @ID import-user-secrets-from-a-file
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Secrets
+// @Param user path string true "User ID, username, or me"
+// @Param request body codersdk.ImportUserSecretsRequest true "Import secrets request"
+// @Success 201 {array} codersdk.UserSecret
+// @Failure 400 {object} codersdk.Response
+// @Failure 409 {object} codersdk.Response
+// @Failure 413 {object} codersdk.Response
+// @Router /api/v2/users/{user}/secrets/batch [post]
+func (api *API) postUserSecretsBatch(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	user := httpmw.UserParam(r)
+
+	// Cap body size before reading; worst-case JSON escaping can inflate
+	// a max-size file several-fold, so 8x gives comfortable headroom.
+	r.Body = http.MaxBytesReader(rw, r.Body, 8*codersdk.MaxSecretsFileBytes)
+	var req codersdk.ImportUserSecretsRequest
+	if !httpapi.Read(ctx, rw, r, &req) {
+		return
+	}
+
+	reqs, err := codersdk.ParseSecretsFile(req.Format, req.Content)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: "Failed to parse secrets file.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Validate every entry and accumulate all errors so the caller can
+	// fix the whole file in one round-trip. Each field is prefixed with
+	// the entry index, e.g. "secrets[2].env_name".
+	var validations []codersdk.ValidationError
+	for i, sreq := range reqs {
+		for _, v := range codersdk.ValidateCreateUserSecretRequest(sreq) {
+			validations = append(validations, codersdk.ValidationError{
+				Field:  fmt.Sprintf("secrets[%d].%s", i, v.Field),
+				Detail: v.Detail,
+			})
+		}
+	}
+	if len(validations) > 0 {
+		writeUserSecretValidationErrors(ctx, rw, http.StatusBadRequest, validations)
+		return
+	}
+
+	// Insert atomically. The per-user-limit trigger fires per row, and
+	// any unique or limit violation aborts the whole transaction, so a
+	// failed import creates nothing. failedIndex records which entry
+	// failed so the error can be attributed to it after the rollback.
+	var created []database.UserSecret
+	failedIndex := -1
+	err = api.Database.InTx(func(tx database.Store) error {
+		for i, sreq := range reqs {
+			s, txErr := tx.CreateUserSecret(ctx, database.CreateUserSecretParams{
+				ID:          uuid.New(),
+				UserID:      user.ID,
+				Name:        sreq.Name,
+				Description: sreq.Description,
+				Value:       sreq.Value,
+				ValueKeyID:  sql.NullString{},
+				EnvName:     sreq.EnvName,
+				FilePath:    sreq.FilePath,
+			})
+			if txErr != nil {
+				failedIndex = i
+				return txErr
+			}
+			created = append(created, s)
+		}
+		return nil
+	}, nil)
+	if err != nil {
+		index := failedIndex
+
+		if conflicts := userSecretConflictValidationErrors(err); len(conflicts) > 0 {
+			if index >= 0 {
+				for i := range conflicts {
+					conflicts[i].Field = fmt.Sprintf("secrets[%d].%s", index, conflicts[i].Field)
+				}
+			}
+			writeUserSecretValidationErrors(ctx, rw, http.StatusConflict, conflicts)
+			return
+		}
+		if resp, ok := userSecretLimitResponse(err); ok {
+			if index >= 0 {
+				resp.Detail = fmt.Sprintf("Entry secrets[%d] (%q): %s", index, reqs[index].Name, resp.Detail)
+			}
+			httpapi.Write(ctx, rw, http.StatusBadRequest, resp)
+			return
+		}
+		if httpapi.IsUnauthorizedError(err) {
+			httpapi.Forbidden(rw)
+			return
+		}
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error importing secrets.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Emit audit logs only after the transaction commits so a rolled-back
+	// batch produces zero logs. One create log is emitted per secret
+	// because database.UserSecret is registered as auditable.
+	auditor := api.Auditor.Load()
+	requestID := httpmw.RequestID(r)
+	auditCtx := context.WithoutCancel(ctx)
+	for _, secret := range created {
+		audit.BackgroundAudit(auditCtx, &audit.BackgroundAuditParams[database.UserSecret]{
+			Audit:     *auditor,
+			Log:       api.Logger,
+			UserID:    user.ID,
+			RequestID: requestID,
+			Status:    http.StatusCreated,
+			IP:        r.RemoteAddr,
+			UserAgent: r.UserAgent(),
+			Action:    database.AuditActionCreate,
+			New:       secret,
+			Old:       database.UserSecret{},
+		})
+	}
+
+	out := make([]codersdk.UserSecret, 0, len(created))
+	for _, secret := range created {
+		out = append(out, db2sdk.UserSecretFromFull(secret))
+	}
+	httpapi.Write(ctx, rw, http.StatusCreated, out)
+}
+
 // @Summary List user secrets
 // @ID list-user-secrets
 // @Security CoderSessionToken

coderd/usersecrets_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/coderd/rbac"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/testutil"
 )
@@ -207,6 +208,22 @@ func TestPostUserSecret(t *testing.T) {
 	})
 }
 
+func TestPostUserSecretForbiddenForAnotherUser(t *testing.T) {
+	t.Parallel()
+	client := coderdtest.New(t, nil)
+	owner := coderdtest.CreateFirstUser(t, client)
+	memberClient, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID, rbac.RoleAuditor())
+	ctx := testutil.Context(t, testutil.WaitMedium)
+
+	_, err := memberClient.CreateUserSecret(ctx, owner.UserID.String(), codersdk.CreateUserSecretRequest{
+		Name:  "forbidden",
+		Value: "value",
+	})
+	var sdkErr *codersdk.Error
+	require.ErrorAs(t, err, &sdkErr)
+	require.Equal(t, http.StatusForbidden, sdkErr.StatusCode())
+}
+
 func TestGetUserSecrets(t *testing.T) {
 	t.Parallel()
 	client := coderdtest.New(t, nil)

coderd/usersecretsimport_test.go

@@ -0,0 +1,343 @@
+package coderd_test
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/coderd/audit"
+	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/rbac"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestImportUserSecrets(t *testing.T) {
+	t.Parallel()
+
+	t.Run("Success", func(t *testing.T) {
+		t.Parallel()
+		auditor := audit.NewMock()
+		client := coderdtest.New(t, &coderdtest.Options{Auditor: auditor})
+		_ = coderdtest.CreateFirstUser(t, client)
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		auditor.ResetLogs()
+
+		secrets, err := client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+			Format:  codersdk.SecretsFileFormatEnv,
+			Content: "ALPHA=a\nBETA=b\nPATH=c\n",
+		})
+		require.NoError(t, err)
+		require.Len(t, secrets, 3)
+		// Valid keys are env-injected, while reserved names are imported
+		// without env injection.
+		assert.Equal(t, "ALPHA", secrets[0].Name)
+		assert.Equal(t, "ALPHA", secrets[0].EnvName)
+		assert.Equal(t, "PATH", secrets[2].Name)
+		assert.Empty(t, secrets[2].EnvName)
+
+		listed, err := client.UserSecrets(ctx, codersdk.Me)
+		require.NoError(t, err)
+		names := make([]string, 0, len(listed))
+		for _, s := range listed {
+			names = append(names, s.Name)
+		}
+		assert.ElementsMatch(t, []string{"ALPHA", "BETA", "PATH"}, names)
+
+		// Exactly one create audit log per imported secret.
+		logs := auditor.AuditLogs()
+		require.Len(t, logs, 3)
+		resourceIDs := make([]string, 0, len(logs))
+		resourceTargets := make([]string, 0, len(logs))
+		for _, l := range logs {
+			assert.Equal(t, database.AuditActionCreate, l.Action)
+			assert.EqualValues(t, http.StatusCreated, l.StatusCode)
+			resourceIDs = append(resourceIDs, l.ResourceID.String())
+			resourceTargets = append(resourceTargets, l.ResourceTarget)
+		}
+		assert.ElementsMatch(t, []string{
+			secrets[0].ID.String(), secrets[1].ID.String(), secrets[2].ID.String(),
+		}, resourceIDs)
+		assert.ElementsMatch(t, []string{"ALPHA", "BETA", "PATH"}, resourceTargets)
+	})
+
+	t.Run("ValuesNotInResponse", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, nil)
+		_ = coderdtest.CreateFirstUser(t, client)
+		ctx := testutil.Context(t, testutil.WaitMedium)
+
+		const secretValue = "super-secret-sentinel-value-123"
+		res, err := client.Request(ctx, http.MethodPost,
+			fmt.Sprintf("/api/v2/users/%s/secrets/batch", codersdk.Me),
+			codersdk.ImportUserSecretsRequest{
+				Format:  codersdk.SecretsFileFormatEnv,
+				Content: "LEAKY=" + secretValue,
+			})
+		require.NoError(t, err)
+		defer res.Body.Close()
+		require.Equal(t, http.StatusCreated, res.StatusCode)
+		body, err := io.ReadAll(res.Body)
+		require.NoError(t, err)
+		assert.NotContains(t, string(body), secretValue)
+	})
+}
+
+func TestImportUserSecretsForbiddenForAnotherUser(t *testing.T) {
+	t.Parallel()
+	client := coderdtest.New(t, nil)
+	owner := coderdtest.CreateFirstUser(t, client)
+	memberClient, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID, rbac.RoleAuditor())
+	ctx := testutil.Context(t, testutil.WaitMedium)
+
+	_, err := memberClient.ImportUserSecrets(ctx, owner.UserID.String(), codersdk.ImportUserSecretsRequest{
+		Format:  codersdk.SecretsFileFormatEnv,
+		Content: "FORBIDDEN=value",
+	})
+	var sdkErr *codersdk.Error
+	require.ErrorAs(t, err, &sdkErr)
+	require.Equal(t, http.StatusForbidden, sdkErr.StatusCode())
+}
+
+func TestImportUserSecretsBodyTooLarge(t *testing.T) {
+	t.Parallel()
+	client := coderdtest.New(t, nil)
+	_ = coderdtest.CreateFirstUser(t, client)
+	ctx := testutil.Context(t, testutil.WaitMedium)
+
+	_, err := client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+		Format:  codersdk.SecretsFileFormatEnv,
+		Content: strings.Repeat("a", 8*codersdk.MaxSecretsFileBytes),
+	})
+	var sdkErr *codersdk.Error
+	require.ErrorAs(t, err, &sdkErr)
+	require.Equal(t, http.StatusRequestEntityTooLarge, sdkErr.StatusCode())
+}
+
+// TestImportUserSecretsValidationRollback verifies that a single
+// invalid entry rejects the whole batch: nothing is created and no
+// audit log is written. The valid sibling entry must not leak through.
+func TestImportUserSecretsValidationRollback(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		badLine string
+	}{
+		// Empty values are always invalid; this is the canonical rollback case.
+		{name: "EmptyValue", badLine: "EMPTY_ONE="},
+		{name: "OversizedValue", badLine: "BIG=" + strings.Repeat("a", codersdk.MaxUserSecretValueBytes+1)},
+		// A slash in the name is invalid regardless of env-name handling.
+		{name: "NameWithSlash", badLine: "bad/name=value"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			auditor := audit.NewMock()
+			client := coderdtest.New(t, &coderdtest.Options{Auditor: auditor})
+			_ = coderdtest.CreateFirstUser(t, client)
+			ctx := testutil.Context(t, testutil.WaitMedium)
+			auditor.ResetLogs()
+
+			_, err := client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+				Format:  codersdk.SecretsFileFormatEnv,
+				Content: "GOOD_ENTRY=fine\n" + tc.badLine,
+			})
+			var sdkErr *codersdk.Error
+			require.ErrorAs(t, err, &sdkErr)
+			assert.Equal(t, http.StatusBadRequest, sdkErr.StatusCode())
+			// Errors are attributed to the offending entry (index 1).
+			require.NotEmpty(t, sdkErr.Validations)
+			for _, v := range sdkErr.Validations {
+				assert.Truef(t, strings.HasPrefix(v.Field, "secrets[1]."),
+					"unexpected field %q", v.Field)
+			}
+
+			listed, err := client.UserSecrets(ctx, codersdk.Me)
+			require.NoError(t, err)
+			assert.Empty(t, listed)
+
+			assert.Empty(t, auditor.AuditLogs())
+		})
+	}
+}
+
+// TestImportUserSecretsConflict verifies that a batch containing an
+// already-existing secret name aborts entirely: the new entry is not
+// created and no audit log is written.
+func TestImportUserSecretsConflict(t *testing.T) {
+	t.Parallel()
+	auditor := audit.NewMock()
+	client := coderdtest.New(t, &coderdtest.Options{Auditor: auditor})
+	_ = coderdtest.CreateFirstUser(t, client)
+	ctx := testutil.Context(t, testutil.WaitMedium)
+
+	_, err := client.CreateUserSecret(ctx, codersdk.Me, codersdk.CreateUserSecretRequest{
+		Name:  "EXISTING",
+		Value: "original",
+	})
+	require.NoError(t, err)
+	auditor.ResetLogs()
+
+	_, err = client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+		Format:  codersdk.SecretsFileFormatEnv,
+		Content: "BRANDNEW=x\nEXISTING=collision",
+	})
+	validation := requireSecretValidation(t, err, http.StatusConflict, "secrets[1].name")
+	assert.Equal(t, "name already in use", validation.Detail)
+
+	// Only the pre-existing secret should remain; BRANDNEW must not be created.
+	listed, err := client.UserSecrets(ctx, codersdk.Me)
+	require.NoError(t, err)
+	require.Len(t, listed, 1)
+	assert.Equal(t, "EXISTING", listed[0].Name)
+
+	assert.Empty(t, auditor.AuditLogs())
+}
+
+// TestImportUserSecretsLimits exercises each per-user cap. A cap
+// tripped mid-batch must roll back every row in the import and, because
+// audit logs are emitted only after the transaction commits, write no
+// import audit logs.
+func TestImportUserSecretsLimits(t *testing.T) {
+	t.Parallel()
+
+	t.Run("CountLimit", func(t *testing.T) {
+		t.Parallel()
+		auditor := audit.NewMock()
+		client := coderdtest.New(t, &coderdtest.Options{Auditor: auditor})
+		_ = coderdtest.CreateFirstUser(t, client)
+		ctx := testutil.Context(t, testutil.WaitLong)
+
+		for i := 0; i < codersdk.MaxUserSecretsPerUserCount-1; i++ {
+			_, err := client.CreateUserSecret(ctx, codersdk.Me, codersdk.CreateUserSecretRequest{
+				Name:  fmt.Sprintf("prefill-%03d", i),
+				Value: "original",
+			})
+			require.NoError(t, err)
+		}
+		before, err := client.UserSecrets(ctx, codersdk.Me)
+		require.NoError(t, err)
+		require.Len(t, before, codersdk.MaxUserSecretsPerUserCount-1)
+
+		auditor.ResetLogs()
+		_, err = client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+			Format:  codersdk.SecretsFileFormatEnv,
+			Content: "COUNT_FIRST=x\nCOUNT_SECOND=y\n",
+		})
+		requireSecretAPIError(t, err, http.StatusBadRequest, "secrets[1]")
+
+		after, err := client.UserSecrets(ctx, codersdk.Me)
+		require.NoError(t, err)
+		require.Len(t, after, len(before))
+		beforeNames := make([]string, 0, len(before))
+		afterNames := make([]string, 0, len(after))
+		for _, secret := range before {
+			beforeNames = append(beforeNames, secret.Name)
+		}
+		for _, secret := range after {
+			afterNames = append(afterNames, secret.Name)
+		}
+		assert.ElementsMatch(t, beforeNames, afterNames)
+		assert.Empty(t, auditor.AuditLogs())
+	})
+
+	t.Run("EnvBytesLimit", func(t *testing.T) {
+		t.Parallel()
+		auditor := audit.NewMock()
+		client := coderdtest.New(t, &coderdtest.Options{Auditor: auditor})
+		_ = coderdtest.CreateFirstUser(t, client)
+		ctx := testutil.Context(t, testutil.WaitLong)
+
+		// Every imported secret is env-injected, so two values that are
+		// each within the per-value cap can still exceed the env-bytes
+		// aggregate together.
+		content := fmt.Sprintf("ENV_A=%s\nENV_B=%s\n",
+			strings.Repeat("a", codersdk.MaxUserSecretValueBytes-16),
+			strings.Repeat("a", 1024))
+		auditor.ResetLogs()
+		_, err := client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+			Format:  codersdk.SecretsFileFormatEnv,
+			Content: content,
+		})
+		requireSecretAPIError(t, err, http.StatusBadRequest, "env_name")
+
+		listed, err := client.UserSecrets(ctx, codersdk.Me)
+		require.NoError(t, err)
+		assert.Empty(t, listed)
+		assert.Empty(t, auditor.AuditLogs())
+	})
+
+	t.Run("TotalBytesLimit", func(t *testing.T) {
+		t.Parallel()
+		auditor := audit.NewMock()
+		client := coderdtest.New(t, &coderdtest.Options{Auditor: auditor})
+		_ = coderdtest.CreateFirstUser(t, client)
+		ctx := testutil.Context(t, testutil.WaitLong)
+
+		// Pre-fill the total-bytes budget to the cap using file-only
+		// secrets (no env_name), which do not count against the smaller
+		// env budget. Creating them via CreateUserSecret directly avoids
+		// going through the import parser.
+		big := strings.Repeat("a", codersdk.MaxUserSecretValueBytes)
+		numBig := codersdk.MaxUserSecretsTotalValueBytes / codersdk.MaxUserSecretValueBytes
+		remainder := codersdk.MaxUserSecretsTotalValueBytes % codersdk.MaxUserSecretValueBytes
+		for i := 0; i < numBig; i++ {
+			_, err := client.CreateUserSecret(ctx, codersdk.Me, codersdk.CreateUserSecretRequest{
+				Name:     fmt.Sprintf("prefill-%03d", i),
+				Value:    big,
+				FilePath: fmt.Sprintf("/tmp/prefill-%03d", i),
+			})
+			require.NoError(t, err)
+		}
+		if remainder > 0 {
+			_, err := client.CreateUserSecret(ctx, codersdk.Me, codersdk.CreateUserSecretRequest{
+				Name:     "prefill-pad",
+				Value:    strings.Repeat("a", remainder),
+				FilePath: "/tmp/prefill-pad",
+			})
+			require.NoError(t, err)
+		}
+
+		before, err := client.UserSecrets(ctx, codersdk.Me)
+		require.NoError(t, err)
+
+		// Reset after the prefill (which legitimately emits create audit
+		// logs) so the assertion below only sees logs from the rolled-back
+		// import.
+		auditor.ResetLogs()
+		_, err = client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+			Format:  codersdk.SecretsFileFormatEnv,
+			Content: "OVERFLOW=x",
+		})
+		requireSecretAPIError(t, err, http.StatusBadRequest, "per-user budget")
+
+		after, err := client.UserSecrets(ctx, codersdk.Me)
+		require.NoError(t, err)
+		assert.Len(t, after, len(before))
+		assert.Empty(t, auditor.AuditLogs())
+	})
+}
+
+func TestImportUserSecretsParseErrors(t *testing.T) {
+	t.Parallel()
+	client := coderdtest.New(t, nil)
+	_ = coderdtest.CreateFirstUser(t, client)
+	ctx := testutil.Context(t, testutil.WaitMedium)
+
+	// Parse-error variety is covered by the parser unit tests; this only
+	// asserts the endpoint maps a parse failure to 400.
+	_, err := client.ImportUserSecrets(ctx, codersdk.Me, codersdk.ImportUserSecretsRequest{
+		Format:  codersdk.SecretsFileFormatJSON,
+		Content: "{not json",
+	})
+	var sdkErr *codersdk.Error
+	require.ErrorAs(t, err, &sdkErr)
+	assert.Equal(t, http.StatusBadRequest, sdkErr.StatusCode())
+}