Skip to content

docs: describe the IdP sync API operations and parameters - #31523

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds a @Description to the 16 IdP sync 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:

  • Continuity Editor: the deployment organization routes used assign_default and organization_assign_default for one setting, so the full-settings and mapping text now say "the default-organization setting" and "the other settings".
  • Copy Editor: rewrote two four-noun phrases ("role sync claim field" and "organization sync claim field").
    The Skeptic rejected 1 finding: sentence length over 25 words in the pointer sentences (the style guide calls the budget a target, not a ceiling).
    Not changed: group, role, and organization sync only take effect with the matching entitlement at login time (enterprise/coderd/enidpsync/groups.go:13, organizations.go:14, role.go:21), but these routes have no license check, so the text makes no license claim.
    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=16 problems=0 thin_params_left=2
ok  	github.com/coder/coder/v2/coderd/coderdtest	1.896s    (-run 'TestEndpointsDocumented|TestSDKFieldsFormatted')
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	2.204s    (-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 (34 leaves, all under paths, all on the 16 routes).
The two remaining thin parameters are the organization parameters on the deployment-level available-fields and field-values routes, which #30124 removes, so this PR leaves them alone.

Claims checked against the code
Route Claim Evidence
/api/v2/organizations/{organization}/settings/idpsync/* organization accepts an ID, a name, or default enterprise/coderd/coderd.go:497 (and the other ExtractOrganizationParam groups), coderd/httpmw/organizationparam.go:72
Organization-scoped GET routes Need read on IdP sync settings in the organization, which Owner, User Admin, Organization Admin, and Organization User Admin have enterprise/coderd/idpsync.go:36, :307; coderd/rbac/roles.go:549 (User Admin), :662 (Organization User Admin); Owner and Organization Admin through allPermsExcept at roles.go:414, :601
Organization-scoped PATCH routes Need update on the same resource, by the same roles idpsync.go:79, :166, :242, :350, :417, :487
/api/v2/settings/idpsync/organization* Deployment-wide, and need site-level read or update, which only Owner and User Admin have idpsync.go:545, :588, :655, :724; roles.go:549
GET .../available-fields, .../field-values (both scopes) Need read on IdP sync settings, in the organization or site-wide coderd/database/dbauthz/dbauthz.go:7555, :7566; idpsync.go:803, :858
GET .../available-fields, .../field-values Read the stored OIDC claims, limited to the organization's members for the organization route and to all users otherwise coderd/database/queries/user_links.sql:64, :84
GET .../field-values Returns 400 when claimField is empty idpsync.go:862
PATCH .../groups Replaces all settings, and rejects legacy_group_name_mapping idpsync.go:89, :114
PATCH .../groups/config Sets field, regex_filter, and auto_create_missing_groups, and keeps mapping idpsync.go:191
PATCH .../roles, .../roles/config Full replace for /roles, and /roles/config sets field and keeps mapping idpsync.go:371, :439
PATCH .../organization, .../organization/config Full replace for the first, and the second sets field and assign_default and keeps mapping idpsync.go:610, :678
All PATCH .../mapping routes Apply add then remove, so an entry in both ends up removed, and keep the other settings idpsync.go:262, :507, :744, :904, :911
All routes No Premium license check on these routes enterprise/coderd/coderd.go:481 to :512 has no RequireFeatureMW
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 says whether it changes one organization or the whole deployment.
  • Each config and mapping route says what it keeps, so a reader can tell it from the full-settings PATCH.
  • No license claim, because nothing gates these routes.
  • One name per setting, and no noun stack of more than 3 words.

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 IdP sync 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