Skip to content

docs: describe the OAuth2 provider API operations and parameters - #31516

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds a @Description to the 21 OAuth2 provider routes tagged Enterprise, and improves the thin parameter text on them.
The REST API reference renders these routes from swagger.json, and they had no description.

doc-check

Fact Checker, Continuity Editor, Copy Editor, and Skeptic ran on the branch diff (author self-check).
Findings fixed in the follow-up commit:

  • Fact Checker: the PUT /api/v2/oauth2-provider/apps/{app} body text said omitting redirect_uris keeps the stored URIs, but sending callback_url alone replaces the first one (coderd/oauth2provider/apps.go:50).
  • Continuity Editor: the authorize descriptions called one entity both an application and a client, so they now say client.
  • Copy Editor: removed "currently", wrote "6" as a digit, cut the four-noun secretID text, and gave the pronouns in the token, revoke, register, authorize and delete-tokens text one clear referent.
    The Skeptic rejected 2 findings: "session" against "session token" (no rule separates them, and the route uses the session credential), and sentence length over 25 words (the style guide calls the budget a target, not a ceiling).
    Left as non-blocking suggestions: the 404 gate names only --oauth2-provider-enable, and the deployment option also takes CODER_OAUTH2_PROVIDER_ENABLE.
    Deterministic checks after the follow-up commit: check_routes.py, both swagger tests, and make lint/emdash pass.

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

check_routes.py: summary: need=21 problems=0 thin_params_left=6
ok  	github.com/coder/coder/v2/coderd/coderdtest	1.119s    (-run 'TestEndpointsDocumented|TestSDKFieldsFormatted')
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	2.984s    (-run TestEnterpriseEndpointsDocumented)
make lint/emdash: OK: no emdash or endash characters found.

A JSON diff of swagger.json against origin/main changes only description values (42 leaves, all under paths, all on the 21 routes).
The six remaining thin parameters are the app path ID, which accepts only a UUID (ParseUUIDParam in coderd/httpmw/oauth2.go:461).

Claims checked against the code
Route Claim Evidence
All /api/v2/oauth2-provider/apps*, /oauth2/*, /.well-known/* Returns 404 unless the OAuth2 provider is enabled with --oauth2-provider-enable (a deployment flag, not an experiment or license) coderd/coderd.go:1104, :1268, :1278, :1289, :2084; coderd/httpmw/oauth2provider.go:15; codersdk/deployment.go:2810
All routes No Premium license check on the OAuth2 provider routes enterprise/coderd/coderd.go has no RequireFeatureMW or entitlement check for OAuth2
GET /api/v2/oauth2-provider/settings, PUT Works while the provider is disabled coderd/coderd.go:2105
GET /api/v2/oauth2-provider/apps, GET .../apps/{app} Any member can read apps coderd/rbac/roles.go:453; coderd/database/dbauthz/dbauthz.go:4601, :4667
GET /api/v2/oauth2-provider/apps user_id filters to apps the user authorized, must be a UUID, and reading another user's needs the Owner role coderd/oauth2provider/apps.go:127, :138; dbauthz.go:4674
POST, PUT, DELETE on apps Needs create, update, or delete on OAuth2 apps, which only Owner has (not in any other role) dbauthz.go:6716, :8401, :2522; coderd/rbac/roles.go:414
PUT /api/v2/oauth2-provider/apps/{app} Keeps stored redirect URIs and scope when omitted, and omitting icon clears it apps.go:290, :323, :331; codersdk/oauth2.go:122
DELETE /api/v2/oauth2-provider/apps/{app} Removes secrets and authorization codes with the app coderd/database/dump.sql:5794, :5800
Secrets routes Read, create, and delete need Owner dbauthz.go:4634, :6731, :2541
POST .../secrets Returns the full secret once, and 400 for a public client coderd/oauth2provider/app_secrets.go:60, :97
DELETE .../secrets/{secretID} The app can no longer authenticate with that secret app_secrets.go:117
GET .../settings Needs read on deployment config (Owner, Auditor) dbauthz.go:4580; coderd/rbac/roles.go:495
PUT .../settings Needs update on deployment config (Owner), and sets whether POST /oauth2/register accepts new clients dbauthz.go:9744; coderd/oauth2provider/registration.go:69
GET /oauth2/authorize Browser without a session goes to login coderd/coderd.go:1122, :1300
POST /oauth2/authorize Code is single use and expires after 10 minutes, and the request needs the user's session coderd/oauth2provider/authorize.go:826; coderd/coderd.go:1300
POST /oauth2/tokens No session token, client credentials as form fields or HTTP Basic coderd/coderd.go:1317; coderd/oauth2provider/tokens.go:197, :266
POST /oauth2/tokens grant_type other than authorization_code or refresh_token gives unsupported_grant_type tokens.go:405, :446
DELETE /oauth2/tokens Uses the user's session token and revokes that user's codes and tokens for the app coderd/coderd.go:1314; coderd/oauth2provider/revoke.go:289, :297
POST /oauth2/revoke No session token, client credentials as in the token endpoint, and 200 for an unknown token or one that belongs to another client coderd/coderd.go:1324; revoke.go:50, :149, :154
GET /.well-known/oauth-authorization-server No session token, and registration_endpoint only when dynamic client registration is on coderd/coderd.go:1266; coderd/oauth2provider/metadata.go:44
GET /.well-known/oauth-protected-resource No session token, and answers only for the root and the MCP endpoint path coderd/coderd.go:1276; metadata.go:61
POST /oauth2/register No session token, 403 unless dynamic client registration is enabled, and returns a registration access token coderd/coderd.go:1328; registration.go:69, :124
/oauth2/clients/{client_id} Authenticates with the registration access token as a bearer token coderd/coderd.go:1331; registration.go:539, :561
PUT /api/v2/oauth2-provider/apps/{app} Omitting both redirect_uris and callback_url keeps the stored redirect URIs coderd/oauth2provider/apps.go:50, :290, codersdk/oauth2.go:122
PUT /oauth2/clients/{client_id} Replaces the registered metadata, and needs redirect_uris registration.go:335; codersdk/oauth2_validation.go:43
Writing rules applied
  • One to three sentences in present tense, the first starting with a verb and standing alone on the endpoint card.
  • One sentence per @Description line.
  • Admin routes and protocol routes are separated: protocol routes name the RFC, who calls them, and which credential they take.
  • Permissions name the built-in roles, traced through dbauthz and coderd/rbac/roles.go.
  • No Premium license claim, because nothing in enterprise/coderd/coderd.go gates these routes.
  • The flag that gates the provider is named in backticks, because it is not an experiment.
  • Routes with no @Security say they don't require a session token and name the credential they use.
  • Full API paths and literal names are in backticks, with no raw <, >, {, or } outside them.
  • No em dashes, en dashes, or semicolons in the new text.
  • One term per concept: the protocol routes say client, the admin routes say application.
  • Digits for 6 and higher, and no noun stack of more than 3 words.

Annotation bugs noticed and left alone are in the report to the author, not this PR.

CI flakes unrelated to this change

test-go-pg (windows-2022) failed TestAPISessionRecoveryWriteDeadline/message in agent/x/agentacp, a package this PR doesn't touch: https://github.com/coder/coder/actions/runs/40937618676/job/123672476795

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

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 OAuth2 provider 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