feat: add API reference and document orgs, auto-linking, mapping, and events

[hperl]

Summary

Brings the SCIM documentation in line with the recent SCIM improvements in Ory Kratos (general-purpose, enterprise-ready SCIM), and fills the integrator-facing gaps.

• New SCIM API reference page (docs/kratos/manage-identities/scim/api-reference.mdx): base URL format, authentication (incl. the single-Bearer-prefix handling), service-discovery endpoints (ServiceProviderConfig, ResourceTypes, Schemas), full Users/Groups CRUD with happy-path request/response shapes, the User/Group/Enterprise-extension schemas, offset and cursor (RFC 9865) pagination, filtering, a SCIM error model + common-error catalogue, and a supported-features matrix.
• Expanded SCIM overview (50_scim.mdx) into a concept + setup hub: how SCIM relates to organizations (one-org-per-identity, the provisioning matrix), auto-linking (matching precedence + verified-domain adoption), cross-organization conflicts (the 409 uniqueness case + resolution), expanded data mapping (the identity extVar, full-replace semantics, and the relationship to the OIDC/SAML Jsonnet mapper), and deprovisioning (active:false vs. hard delete).
• Corrected the Events section against the implementation: real event names (SCIMGroupCreated/Updated/Deleted), the member-event nuance, the previously-undocumented SCIMProvisioningError event, and accurate attribute keys (SCIMClient, group/error attributes).
• Jsonnet reference: documented the SCIM identity extVar and added a working SCIM mapping example.
• Organizations page: cross-linked to the SCIM org/conflict behavior.
• Wired the API reference page into the network sidebar.

Also fixed three things that were outright incorrect in the live docs: the active default (now defaults to true), the broken identity-merge mapping example, and the misleading "set the base URL" phrasing.

Test Plan

• npm install && npx docusaurus build succeeds
• No broken-link/anchor warnings reference the SCIM pages or their new anchors
• Visual review of the rendered pages

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added an SCIM API reference entry to the documentation sidebar to make SCIM integration docs easier to find.
• Documentation
  • Expanded documentation syntax highlighting to include the http language.

[coderabbitai]

📝 Walkthrough

Walkthrough

Two configuration changes update the documentation infrastructure: a new SCIM API reference document is added to the network sidebar navigation, and HTTP syntax highlighting support is enabled in Prism for code block display.

Changes

Documentation Configuration

Layer / File(s)	Summary
Add SCIM api-reference to sidebar items sidebars-network.ts	Inserts "kratos/manage-identities/scim/api-reference" into the SCIM category's items array in the network sidebar configuration.
Add HTTP syntax highlighting support docusaurus.config.ts	Extends Prism's additionalLanguages array to include "http" for syntax-highlighted HTTP code blocks in documentation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• ory/docs#2589: Also modifies sidebars-network.ts by adding a new entry to the networkSidebar items list for a specific sidebar category.

Suggested labels

upstream

Suggested reviewers

• aeneasr
• zepatrik
• vinckr
• piotrmsc

Poem

🐇 A sidebar gains breadth, a new entry appears,
While HTTP syntax glows bright, crystal clear.
Two small changes, though humble they be,
Make docs more complete, and the code pretty!
Configuration hops forward, one step at a time. 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The PR title describes adding API reference and documentation, but the actual changeset only adds one sidebar entry and one language to Prism config—much smaller in scope than the comprehensive SCIM documentation work described in the PR objectives.	The title appears to summarize broader documentation work, but the changeset shows minimal file modifications. Clarify whether this is a partial merge or if the title should reflect only the sidebar/config updates shown in the raw summary.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description provides a comprehensive summary of changes, a test plan, and references design context, though it does not explicitly reference a related issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch hperl/scim-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates the Ory Kratos SCIM documentation to match recent SCIM server behavior in Ory Network, adding a dedicated API reference and expanding the SCIM overview to cover organizations, auto-linking/conflicts, mapping, deprovisioning, and events.

Changes:

• Added a new SCIM API reference page and linked it into the Network sidebar.
• Expanded the SCIM overview with organization scoping behavior, auto-linking rules, conflict handling, mapping semantics, deprovisioning guidance, and corrected event names/attributes.
• Updated the Jsonnet mapping reference to document SCIM inputs (including the existing identity) and provide a SCIM mapping example; cross-linked organizations docs to SCIM provisioning behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sidebars-network.ts	Adds the SCIM API reference page to the SCIM sidebar category.
docs/kratos/reference/jsonnet.mdx	Documents SCIM Jsonnet inputs and adds a SCIM mapping example + cross-links.
docs/kratos/organizations/organizations.mdx	Adds guidance linking org pre-provisioning to SCIM provisioning and conflict behavior.
docs/kratos/manage-identities/scim/api-reference.mdx	Introduces a comprehensive SCIM API reference (auth, discovery, CRUD, schemas, pagination/filtering, errors, features).
docs/kratos/manage-identities/50_scim.mdx	Expands SCIM overview to include org scoping, auto-linking/conflicts, mapping semantics, deprovisioning, events, and limitations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gaultier]

LGTM!
Have we checked that events listed here https://www.ory.com/docs/actions/live-events#event-names are up-to-date as well (regarding SCIM events)?

[hperl]

LGTM! Have we checked that events listed here https://www.ory.com/docs/actions/live-events#event-names are up-to-date as well (regarding SCIM events)?

Yes, those didn't change.