Content/audience question (picking up @matifali's open thread on this file): this section lives in a user guide but reads in reference-doc register — it leads with a raw POST /api/v2/users/{user}/secrets/batch route and the codersdk.Client.ImportUserSecrets Go method. A user-guide reader is more likely to expect a CLI or UI entry point, with the wire/SDK details left to the API reference (which already documents this endpoint).

Given #26725 sits on top of this in the stack and may add the user-facing surface, a couple of options:

• Reframe this around the user-facing entry point (CLI/UI) and link the API reference for the wire format, or
• Hold this user-guide section until that surface lands, keeping only the API-reference coverage for now.

The technical content itself is accurate — formats, atomic rollback, and the empty-env_name behavior for reserved/invalid keys all match the implementation. This is purely about placement/audience.

Content note (following up on @matifali's thread): with the upload UI in #26725 closed/stale and no CLI in the stack, this API/SDK path is currently the only way to bulk-import — so keeping it documented here is the right call, and I'd keep the section. Placement isn't a concern either, since docs IA is being restructured separately.

One optional polish for the user-guide audience: a short task-oriented lead-in (when/why you'd reach for bulk import) plus a small example payload — a few lines of env content and the matching request body — would make it read a bit less like a route-and-method pointer. Not blocking. The technical content (formats, atomic rollback, empty env_name for reserved/invalid keys) is accurate as-is.

Oh I will be reviving #26725, it was just opened a while ago. Once this is merged that will be reopened :)

I ended up pulling the section from this page entirely per Atif's request to keep reference docs off the user guide. I'll bring the task-oriented version (lead-in + example) back with the UI PR.

From Coder Agents:

FYI for reviewers (not a change request): this teaches the shared Read helper to return 413 on *http.MaxBytesError, which is a strict improvement over the old behavior (an oversized body previously surfaced as 400 "Request body must be valid JSON."). Flagging only that it's cross-cutting — the new status now applies to every endpoint that wraps its body in http.MaxBytesReader, not just the new batch import. That looks intentional and it's covered by the new TestRead/BodyTooLarge case; noting it so the shared-behavior change is a conscious sign-off rather than an incidental side effect.

Yep, intentional. 413 is the right status for an oversized body, and it only affects endpoints already using http.MaxBytesReader 👍

TIL of this syntax vs errors.As

It won't surprise the user, right?

Yeah, we enforce that validation across the User Secrets interfaces

This is not part of this PR, but agent flagged a bug:

Bug: single-quoted values silently swallow trailing data

quotedInner (codersdk/usersecretsimport.go:225) doesn't find the first closing quote like the double-quote path does. It just trims trailing whitespace and checks
whether the last character of the line is a quote, then strips first-and-last:

func quotedInner(v string, quote byte) (string, bool) {
      trimmed := strings.TrimRight(v, " \t")
      if len(trimmed) < 2 || trimmed[len(trimmed)-1] != quote {
              return "", false
      }
      return trimmed[1 : len(trimmed)-1], true
}

Actual behavior:

┌────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│       Input        │                                                  Result                                                   │
├────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ KEY='abc' # 'note' │ value = abc' # 'note ⚠️  silent                                                                            │
├────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ KEY='a'b'          │ value = a'b ⚠️  silent                                                                                     │
├────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ KEY='a' 'b'        │ value = a' 'b ⚠️  silent                                                                                   │
├────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ KEY='abc' extra    │ error, but message says "missing closing single quote" (wrong; the quote is closed, the data is trailing) │
└────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

I'll create a follow up PR for this shortly