Skip to content

docs: describe the Users API operations and parameters - #31528

Closed
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-users
Closed

nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-users

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

The REST API reference renders each route from swagger.json, and the 34 Users routes had no description.
This adds a @Description to each of them and rewrites the parameter text on them, so each endpoint page says what the call does, who can call it, and what to know before calling it.

Merge notes

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

Verification

$ python3 check_routes.py 01-users.txt
summary: need=34 problems=0 thin_params_left=0

$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.607s

$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	1.905s

A JSON diff of swagger.json against main changes only description values: 34 added to operations and 42 rewritten on parameters, all on the 34 routes in scope.

Claims checked against the code

Role grants come from coderd/rbac/roles.go: Owner has all permissions (:414), Auditor reads users (:488), Template Admin reads users (:521), User Admin has create, read, update, delete, and personal read and update on users (:539), Organization Admin and Organization User Admin read users site-wide (:594, :650), and Member reads and updates only its own personal data (:463).

Route Claim Evidence
GET /api/v2/users Returns only the users you can read coderd/database/dbauthz/dbauthz.go:5778
GET /api/v2/users q keys, and a bare term matches email, username, or name coderd/searchquery/search.go:206, coderd/database/queries/users.sql:447
GET /api/v2/users limit defaults to 0 (all results), after_id and offset page results coderd/pagination.go:19, coderd/users.go:396, coderd/users.go:417
POST /api/v2/users Creating a user needs create on users (Owner, User Admin) and permission to assign the requested roles coderd/database/dbauthz/dbauthz.go:6939, coderd/rbac/roles.go:539
POST /api/v2/users Service accounts need a Premium license coderd/users.go:503
POST /api/v2/users organization_ids needs at least one organization, service accounts can't have an email or password coderd/users.go:537, coderd/users.go:471
GET /api/v2/users/authmethods Doesn't require a session token coderd/coderd.go:1702, router group without apiKeyMiddleware
GET /api/v2/users/first Returns 200 or 404 by user count, no session token coderd/users.go:160, coderd/coderd.go:1700
POST /api/v2/users/first Creates an Owner in the default organization, 409 once a user exists, no session token coderd/users.go:207, coderd/users.go:270, coderd/coderd.go:1701
POST /api/v2/users/logout Deletes the calling key and the application connect keys, clears the cookie coderd/userauth.go:710, coderd/userauth.go:718, coderd/userauth.go:732
GET /api/v2/users/oauth2/github/callback Browser redirect from GitHub, no session token, redirect_url JSON when device flow is on coderd/coderd.go:1722, coderd/userauth.go:1153
GET /api/v2/users/oauth2/github/device Needs GitHub OAuth2 and device flow, no session token, returns device_code, user_code, verification_uri coderd/userauth.go:857, coderd/userauth.go:864, codersdk/externalauth.go:123
GET /api/v2/users/oidc-claims Returns 400 unless the login type is oidc, userinfo claims win on conflict coderd/users.go:102, codersdk/users.go:451
GET /api/v2/users/oidc/callback Browser redirect from the identity provider, no session token coderd/coderd.go:1729, coderd/userauth.go:1590
GET /api/v2/users/{user} Reading other users needs read on users coderd/database/dbauthz/dbauthz.go:5580, coderd/rbac/roles.go:488, :521, :539, :594, :650
DELETE /api/v2/users/{user} Needs delete on users (Owner, User Admin), can't delete yourself or a user with workspaces coderd/database/dbauthz/dbauthz.go:8884, coderd/users.go:703, coderd/users.go:723
DELETE /api/v2/users/{user} Notifies user admins coderd/users.go:743
GET, PUT /api/v2/users/{user}/appearance Own settings, or personal read and update on users (Owner, User Admin) coderd/database/dbauthz/dbauthz.go:5565, :9108, :9064, coderd/rbac/roles.go:463, :539
PUT /api/v2/users/{user}/appearance Omitting theme_mode keeps the saved mode and themes, sync takes light and dark themes coderd/users.go:1351, codersdk/users.go:268
GET, PUT /api/v2/users/{user}/preferences Same permission as appearance, omitted fields keep their values, accepted values for each field coderd/database/dbauthz/dbauthz.go:5767, coderd/users.go:1528, coderd/users.go:1570, codersdk/users.go:298
GET, PUT /api/v2/users/{user}/gitsshkey Own key, or personal read and update on users (Owner, User Admin), never returns the private key coderd/database/dbauthz/dbauthz.go:4307, :8275, coderd/gitsshkey.go:80
POST /api/v2/users/{user}/keys Another user's key needs create on API keys (Owner only), can't exceed the calling key coderd/database/dbauthz/dbauthz.go:6454, coderd/apikey/apikey.go:179
GET /api/v2/users/{user}/keys/tokens Filtered to tokens you can read, include_expired defaults to false coderd/apikey.go:384, coderd/apikey.go:355
GET /api/v2/users/{user}/keys/tokens include_all lists tokens for every user you can read coderd/apikey.go:354
POST /api/v2/users/{user}/keys/tokens Default lifetime comes from the deployment's default token lifetime, maximum differs for Owners coderd/apikey.go:129, coderd/apikey.go:597, codersdk/deployment.go:3513, :3527, :3538
POST /api/v2/users/{user}/keys/tokens scopes default to the calling key's scopes, a name is generated when token_name is omitted, lifetime is nanoseconds coderd/apikey/apikey.go:183, coderd/apikey.go:120, codersdk/apikey.go:50
GET /api/v2/users/{user}/keys/tokens/{keyname} Reading another user's token needs read on API keys (Owner only) coderd/database/dbauthz/dbauthz.go:3177, coderd/database/modelmethods.go:430
GET, DELETE, PUT /api/v2/users/{user}/keys/{keyid}, /expire Read, delete, and update go through the key's owner, so other users' keys need the Owner role coderd/database/dbauthz/dbauthz.go:3173, :2219, :7870, coderd/database/modelmethods.go:430
PUT /api/v2/users/{user}/keys/{keyid}/expire Does nothing for an already expired key coderd/apikey.go:500
GET /api/v2/users/{user}/keys/{keyid} The key ID is the part before the hyphen coderd/apikey/apikey.go:54, coderd/apikey/apikey.go:102
GET /api/v2/users/{user}/login-type Only the caller's own login type coderd/users.go:836
GET /api/v2/users/{user}/organizations Filtered to organizations you can read coderd/users.go:2056
GET /api/v2/users/{user}/organizations/{organizationname} Looks up by organization name only, doesn't check membership coderd/users.go:2083
PUT /api/v2/users/{user}/password Revokes all of the user's API keys coderd/users.go:1876
PUT /api/v2/users/{user}/password Needs update personal on users, only Owners change an Owner's password, old_password for yourself, password login type only coderd/users.go:1768, :1773, :1797, :1805
PUT /api/v2/users/{user}/profile Changing a username needs update on users coderd/users.go:1031
PUT /api/v2/users/{user}/profile Avatar applies only to password and none login types coderd/users.go:1065
GET /api/v2/users/{user}/roles Needs personal read on users for other users coderd/users.go:1912
PUT /api/v2/users/{user}/roles Assignable roles come from the caller's roles, User Admin can assign only Member at site level coderd/database/dbauthz/dbauthz.go:1431, coderd/rbac/roles.go:827
PUT /api/v2/users/{user}/roles Can't change your own roles, or OIDC users while role sync is on coderd/users.go:1984, coderd/users.go:1974
PUT /api/v2/users/{user}/status/activate Needs update on users (Owner, User Admin) coderd/database/dbauthz/dbauthz.go:9057
PUT /api/v2/users/{user}/status/suspend Needs update on users, can't suspend yourself or an Owner coderd/database/dbauthz/dbauthz.go:9057, coderd/users.go:1154, coderd/users.go:1158
PUT /api/v2/users/{user}/status/suspend Suspended users can't sign in coderd/userauth.go:632

Identifiers left out of the text, per the content guidelines: the CLI flags for the default and maximum token lifetime (--default-token-lifetime, --max-token-lifetime, --max-admin-token-lifetime) in codersdk/deployment.go.

Writing rules applied
  • One to three sentences per route, present tense, active voice, first sentence starts with a verb and stands alone.
  • Permission sentences name the built-in roles by display name and trace to dbauthz and roles.go.
  • Routes outside the session-token middleware say "Doesn't require a session token."
  • Callback routes say the identity provider redirects the browser there and you don't call them directly.
  • Shared user parameter wording is copied exactly on every route behind ExtractUserParam.
  • limit, offset, and after_id use the shared pagination wording because ParsePagination is the only source of defaults.
  • Body parameters say what the body is and list accepted values taken from the validators.
  • Literals, field names, and full API paths are in backticks, and the text has no dashes, semicolons, or raw angle brackets and braces.
Annotation issues noticed and not changed

These are outside this PR's scope.

  • GET /api/v2/users/first, POST /api/v2/users/first, GET /api/v2/users/authmethods, GET /api/v2/users/oauth2/github/callback, GET /api/v2/users/oauth2/github/device, and GET /api/v2/users/oidc/callback have @Security CoderSessionToken, but the router serves them without apiKeyMiddleware (coderd/coderd.go:1699).
    assertSecurityDefined doesn't list them.
  • GET /api/v2/users/{user}/keys/tokens reads an include_all query parameter (coderd/apikey.go:354) that has no @Param.
  • GET /api/v2/users/oauth2/github/callback documents only 307, but it returns 200 with redirect_url when device flow is on (coderd/userauth.go:1153).
  • GET /api/v2/users/{user}/keys/{keyid}, DELETE, and PUT .../expire look the key up by ID alone, so the user path segment doesn't scope the lookup.
  • GET /api/v2/users/{user}/organizations/{organizationname} doesn't use user after resolving it.
  • POST /api/v2/users documents codersdk.CreateUserRequest while the handler reads CreateUserRequestWithOrgs, an alias with the same fields.

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.
This adds a description to each of the 34 Users routes and rewrites the
thin or non-standard parameter text on them.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Users 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