Skip to content

docs: describe the Authorization API operations and parameters - #31529

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

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

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

The REST API reference renders each route from swagger.json, and the 7 Authorization routes had no description.
This adds a @Description to each of them and rewrites the body and path parameter text on them, so each endpoint page says what the call does 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 02-authorization.txt
summary: need=7 problems=0 thin_params_left=0

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

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

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

Claims checked against the code
Route Claim Evidence
GET /api/v2/auth/scopes Doesn't require a session token coderd/coderd.go:1475 (registered outside apiKeyMiddleware), coderd/coderdtest/swaggerparser.go:368
GET /api/v2/auth/scopes Lists all, application_connect, the coder:* composite scopes, and the resource:action scopes coderd/rbac/scopes_catalog.go:90, coderd/rbac/scopes_catalog.go:198
POST /api/v2/authcheck Needs a session token, results account for the user's roles and the key's scopes coderd/coderd.go:1953, coderd/authorize.go:198
POST /api/v2/authcheck At most 10 checks can set resource_id, each check needs resource_type coderd/authorize.go:219, coderd/authorize.go:226, coderd/authorize.go:246
POST /api/v2/users/login Doesn't require a session token coderd/coderd.go:1711, coderd/coderdtest/swaggerparser.go:369
POST /api/v2/users/login Password login type only, 403 when password authentication is turned off coderd/userauth.go:614, coderd/userauth.go:621
POST /api/v2/users/login Returns session_token and sets the session cookie coderd/userauth.go:566, coderd/userauth.go:569
POST /api/v2/users/otp/request Doesn't require a session token, 403 when password authentication is turned off coderd/coderd.go:1712, coderd/userauth.go:249
POST /api/v2/users/otp/request Returns 204 whether or not the account exists coderd/userauth.go:264
POST /api/v2/users/otp/request Passcode expires after 20 minutes, delivered as a notification coderd/coderd.go:525, coderd/userauth.go:280, coderd/userauth.go:316
POST /api/v2/users/otp/change-password Doesn't require a session token coderd/coderd.go:1714, coderd/coderdtest/swaggerparser.go:371
POST /api/v2/users/otp/change-password 400 for a wrong or expired passcode, or a new password that matches the old one coderd/userauth.go:407, coderd/userauth.go:420
POST /api/v2/users/otp/change-password Revokes all of the user's API keys, new password must meet the requirements coderd/userauth.go:443, coderd/userauth.go:371
POST /api/v2/users/validate-password Doesn't require a session token coderd/coderd.go:1713, registered in the rate-limited group without apiKeyMiddleware
POST /api/v2/users/validate-password Returns valid and details coderd/userauth.go:494
POST /api/v2/users/{user}/convert-login Requires the user's current password, password login type only coderd/userauth.go:130, coderd/userauth.go:139
POST /api/v2/users/{user}/convert-login Target type is github or oidc coderd/userauth.go:113
POST /api/v2/users/{user}/convert-login State string and cookie expire after 5 minutes, and the callback reads the cookie coderd/userauth.go:176, coderd/userauth.go:204, coderd/userauth.go:2121
Writing rules applied
  • One to three sentences per route, present tense, active voice, first sentence starts with a verb and stands alone.
  • Routes outside the session-token middleware say "Doesn't require a session token."
  • Statuses, field names, and full API paths are in backticks, and the text has no dashes, semicolons, or raw angle brackets and braces.
  • Body parameters say what the body holds instead of repeating the type name.
  • The user path parameter uses the shared wording, because the route uses ExtractUserParam.
  • "Turned off" replaces "disabled" for password authentication, per the word-choice rule.
Annotation issues noticed and not changed

These are outside this PR's scope.

  • POST /api/v2/users/validate-password has @Security CoderSessionToken, but the router serves it without apiKeyMiddleware (coderd/coderd.go:1713), and assertSecurityDefined doesn't list it.
  • POST /api/v2/users/{user}/convert-login takes user through ExtractUserParam, but the handler signs in with the path user's own email and the password in the body, so it needs that user's password and doesn't compare the path user to the session user.

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 7 Authorization 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 Authorization 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