Skip to content

docs: describe the Secrets API operations and parameters - #31545

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-secrets
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-secrets

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds descriptions for the 6 Secrets routes and improves 12 of their parameters.
The REST API reference renders these routes from swagger.json, and they had no description.

Merge notes

This PR doesn't touch the exemption lists from #31473.
If #31473 merges first, TestEndpointsDocumented names each route on this PR to remove from those lists.

Verification

summary: need=6 problems=0 thin_params_left=0
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.366s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.579s

A JSON diff of coderd/apidoc/swagger.json against origin/main changes only description values on the routes in this PR.

Claims checked against the code
Route Claim Evidence
GET /api/v2/users/{user}/secrets No built-in role grants access to other users' secrets, so only the user can read them coderd/rbac/roles.go:422 (Owner excludes ResourceUserSecret), coderd/rbac/roles.go:601 (Organization Admin excludes it), coderd/rbac/roles.go:458-459 (Member keeps it for own resources), coderd/database/dbauthz/dbauthz.go:7444-7450
GET /api/v2/users/{user}/secrets, GET /api/v2/users/{user}/secrets/{name}, POST /api/v2/users/{user}/secrets Responses omit the secret value coderd/database/db2sdk/db2sdk.go:2439-2465
POST /api/v2/users/{user}/secrets At most 50 secrets and 200 KiB in total per user codersdk/usersecretvalidation.go:64,69
POST /api/v2/users/{user}/secrets value up to 24 KiB; name and value required; enabled defaults to true codersdk/usersecretvalidation.go:97,225-232, coderd/usersecrets.go:174-178
POST /api/v2/users/{user}/secrets Enabled secret is injected as env_name, file_path, or both, and needs one of them codersdk/usersecrets.go:20-24,31-35, codersdk/usersecretvalidation.go:258
POST /api/v2/users/{user}/secrets/batch Formats env, json, yaml; content up to 1 MiB; up to 50 entries codersdk/usersecretsimport.go:14-26,75-77
POST /api/v2/users/{user}/secrets/batch Import is atomic (one transaction, nothing created on failure) coderd/usersecrets.go:274-284
POST /api/v2/users/{user}/secrets/batch Keys that aren't valid environment variable names import disabled with no env_name codersdk/usersecretsimport.go:85-100
PATCH /api/v2/users/{user}/secrets/{name} At least one field required; an enabled secret must keep env_name or file_path coderd/usersecrets.go:455-460, 519-528
all six routes user accepts ID, username, or me coderd/coderd.go:1758, coderd/httpmw/userparam.go:51-70
POST /api/v2/users/{user}/secrets Secrets that set an env_name total at most 24 KiB per user coderd/database/migrations/000509_user_secrets_limits.up.sql:55,66-100
doc-check self-check

Ran in author self-check mode on the branch diff, annotation text only: Fact Checker, Continuity Editor, Copy Editor, and then the Skeptic.
The other personas didn't run because no Markdown page was written by hand, and docs/reference/api/ is generated.
Fact Checker: Found one incomplete limit: the create description gave the 200 KiB total but not the 24 KiB cap on secrets that set an env_name, which the database trigger enforces first (coderd/database/migrations/000509_user_secrets_limits.up.sql:55-100).
Fixed in a follow-up commit.
Continuity Editor: No findings.
The user wording matches the shared text and the handlers use httpmw.ExtractUserParam.
Copy Editor: No findings.
The "disabled" wording was reworded before the first push.
Skeptic: kept 1 and rejected 2.
One nbsp finding for "24 KiB" and "1 MiB", rejected because Coder.UnitSpacing skips pages generated from Go source.
One claim that the 24 KiB value limit is wrong for encrypted deployments, rejected because the API validates plaintext length against that constant (codersdk/usersecretvalidation.go:346-353) and the description states the API limit.
No blocking findings remain.

Writing rules applied
  • One to three present-tense, active-voice sentences, addressed to "you", with the first sentence starting with a verb.
  • Permission sentences name the built-in roles by display name, each traced to coderd/rbac/roles.go and the handler or dbauthz check.
  • Premium license, experiment, and authentication sentences appear only where the code gates the route.
  • Streams say that the route upgrades to a WebSocket and what each message carries.
  • Full API paths and exact field names, parameter names, and values are in backticks.
  • Parameter text states what the value selects, its accepted forms, and its default and limits from the code.
  • Shared parameters (user, limit, offset) use the shared wording only where the handler matches it.
  • No em dashes, en dashes, spaced double hyphens, semicolons in prose, or raw angle brackets and braces outside backticks.

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

The REST API reference renders these routes from swagger.json, and they had no description.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

The create description now states the 24 KiB cap on secrets that set an env_name, which binds before the 200 KiB total.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Secrets API operations and parameters. The claims table above still covers that commit.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant