Skip to content

docs: describe the SCIM API operations and parameters - #31517

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds a @Description to the 6 SCIM 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: GET /scim/v2/Users and GET /scim/v2/Users/{id} said "Always", but only the legacy handler behaves that way. The new handler returns real users (enterprise/coderd/scim/users.go:181, :192), so the text now names CODER_SCIM_USE_LEGACY, which defaults to on (codersdk/deployment.go:3791).
  • Copy Editor: rewrote "SCIM service provider configuration" (four-noun stack), and cut the POST, PUT, and PATCH text to three sentences by dropping the dormant-after-reactivation notes.
    The Skeptic rejected 1 finding: "calls this" in the authentication sentence (the pronoun has one referent, the route). The text now says "authenticates with" anyway.
    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=6 problems=0 thin_params_left=0
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.780s    (-run 'TestEndpointsDocumented|TestSDKFieldsFormatted')
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	1.116s    (-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 (12 leaves, all under paths, all on the 6 routes).

Claims checked against the code
Route Claim Evidence
All routes Need a Premium license enterprise/coderd/scimroutes.go:46 (RequireFeatureMW(codersdk.FeatureSCIM))
All routes These annotations document the legacy SCIM handler, which CODER_SCIM_USE_LEGACY selects and which defaults to on scimroutes.go:33; codersdk/deployment.go:3787, :3791
All routes Return 404 when no SCIM API key is configured scimroutes.go:17
All routes Authenticate with the SCIM API key in the Authorization header (CODER_SCIM_AUTH_HEADER), not a session token scimroutes.go:47; legacyscim.go:77, :88; codersdk/deployment.go:3776
GET /scim/v2/ServiceProviderConfig Needs the SCIM API key, because AuthMiddleware wraps the whole handler scimroutes.go:45, :47; enterprise/coderd/scim_test.go:380
GET /scim/v2/Users Returns an empty list with the legacy handler, which CODER_SCIM_USE_LEGACY selects and which defaults to on legacyscim.go:170, :186; codersdk/deployment.go:3787, :3791; the new handler returns real users at scim/users.go:192
GET /scim/v2/Users/{id} Returns 404 with the legacy handler legacyscim.go:200, :223; the new handler returns the user at scim/users.go:181
POST /scim/v2/Users Requires active and a primary email, matches an existing user by email or username, and creates users with the OIDC login type legacyscim.go:295, :309, :314, :392
PATCH and PUT /scim/v2/Users/{id} active is required and only the status changes legacyscim.go:466, :471, :538, :571, and scimUserStatus at :604
PUT /scim/v2/Users/{id} Returns 400 when userName is set and differs from the current username legacyscim.go:566
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.
  • Permissions name the built-in roles, traced through the handler's api.Authorize call and coderd/rbac/roles.go.
  • 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.
  • Each route names the credential it takes (the SCIM API key) and who calls it (the identity provider's SCIM client).
  • The Premium license is stated because the route sits behind RequireFeatureMW.

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