docs: onboarding portal (#2181)

* feat: onboarding portal

* feat: add section under kratos/organizations

* feat: tweaks

* feat: tweaks

* feat: add API tab content

* fix: tweak

* fix: tweak

* feat: update API docs and screenshot

* fix: add context and fix delete api

* fix: wording

* fix: tweaks

* fix: move note to the start

* fix: updates and tweaks

* fix: wording

* fix: mention minimum expiry

* fix: remove bold formatting

* fix: limitations

* chore: update api key operations

* fix: link to api key section

* chore: format

* fix: address review comments

Author: niwsa

docs/concepts/personal-access-token.mdx

@@ -158,6 +158,7 @@ create, read, update, delete.
 | Delete projects                                                                                     | Yes                  | No                                   |
 | List and invite members                                                                             | Yes                  | No                                   |
 | CRUD B2B SSO organizations                                                                          | Yes                  | No                                   |
+| CRUD onboarding portal links                                                                        | Yes                  | No                                   |
 | CRUD project API keys                                                                               | Yes                  | No                                   |
 | CRUD identities                                                                                     | No                   | Yes                                  |
 | CRUD OAuth2 clients                                                                                 | No                   | Yes                                  |

docs/kratos/organizations/_static/onboarding-portal-link.png

@@ -389,3 +389,175 @@ local claims = std.extVar('claims');
   },
 }
 ```
+
+## Onboarding portal
+
+:::note
+
+Before proceeding, ensure you are on a plan that supports onboarding portal. It is available exclusively on select enterprise
+plans. The portal requires that you enable Account Experience 2.0. Please contact us [Ory Support](mailto:[email protected]) if you
+have any questions or feedback.
+
+:::
+
+Onboarding portal is a powerful tool designed to simplify complex identity and access management tasks for businesses and their
+partners.
+
+### Streamline organization onboarding
+
+The onboarding portal addresses the often-burdensome process of setting up and managing identity connections with external
+organizations. Traditionally, integrating with a customer's or partner's identity provider (IdP) for single sign-on (SSO) or
+synchronizing user directories involves manual, error-prone configurations. This often requires deep technical expertise in
+protocols such as SAML.
+
+Onboarding portal aims to:
+
+- Simplify complex integrations: By providing a self-service or guided onboarding experience, they abstract away the underlying
+  technical complexities of SAML. This means IT administrators on the client side don't need to be SAML experts to connect their
+  organization's identity system.
+- Reduce onboarding time: Instead of lengthy back-and-forth communication and manual configuration, an onboarding portal link
+  allows an external administrator to configure the connection directly through a user-friendly interface. This drastically
+  reduces the time and effort required to establish new B2B integrations.
+- Enhance security and control: Onboarding portal links are designed to be shareable without exposing sensitive information. The
+  administrator receiving the link can configure their side of the connection securely, maintaining control over their IdP
+  settings while establishing a trusted connection with your application.
+- Enable Self-Service for Organizations: For SaaS providers, this means empowering your customers to self-onboard and manage their
+  own SSO connections, freeing up your engineering and support teams. Support Scalability for B2B Models: As your application
+  grows and serves more enterprise clients, manually managing each integration becomes unsustainable. These features provide a
+  scalable solution for onboarding and managing a large number of organizational customers.
+- Validate SSO Connections instantly: The onboarding portal includes the ability to immediately test the configured SSO
+  connection. This allows IT administrators to verify that the integration works as expected before deploying it to their users,
+  reducing troubleshooting time and ensuring a smooth rollout.
+
+These features are relevant for:
+
+- SaaS (Software-as-a-Service) providers: SaaS companies offer services to other businesses (B2B) or to businesses that then serve
+  their own customers (B2B2C). This is crucial for enabling enterprise clients to use their existing corporate identity systems
+  (for example, Microsoft Entra ID, Okta, Google Workspace) for seamless access to the SaaS application.
+- Enterprise IT administrators: These individuals in your customer organizations are responsible for managing their internal
+  identity providers and user directories. They use the onboarding portal to configure the connection to your application.
+- Developers and architects building multi-tenant applications: These individuals implement robust and scalable identity
+  management for applications that serve multiple organizations. Each organization has its own authentication and user
+  provisioning requirements.
+
+Current limitations:
+
+- The onboarding portal currently supports Microsoft Entra ID and Okta. You can also connect all SAML-compliant providers using
+  the custom SAML provider option. If you don't find your provider listed, please [contact us](https://www.ory.sh/contact/). While
+  OIDC and SCIM are part of Ory Network's capabilities, their integration with the onboarding portal is still under development.
+
+### Manage onboarding portal links
+
+```mdx-code-block
+<Tabs groupId="console-or-api">
+<TabItem value="console" label="Ory Console">
+```
+
+#### Create a link
+
+Go to <ConsoleLink route="project.authentication.organizations" /> and continue by configuring the selected organization.
+
+In the **Edit Organization** page, under the **Onboarding Portal** section, click **Generate link** to create a link. You can then
+share this link with the organization admins.
+
+```mdx-code-block
+import BrowserWindow from "@site/src/theme/BrowserWindow"
+
+<BrowserWindow url="https://console.ory.sh/projects/<id>/authentication/organizations/<id>/edit">
+    ![Onboarding portal link](./_static/onboarding-portal-link.png)
+</BrowserWindow>
+```
+
+```mdx-code-block
+</TabItem>
+<TabItem value="api" label="API">
+```
+
+Onboarding portal links can also be managed using the Ory API. To authenticate your requests, create a
+[workspace API key](/concepts/personal-access-token#authorizing-ory-network-workspace-admin-apis). All examples below use curl to
+make HTTP requests. You can use any HTTP client to make these requests. Before copy & pasting the following examples, export your
+PROJECT_ID,ORGANIZATION_ID and WORKSPACE_API_KEY:
+
+#### Create an onboarding portal link
+
+```shell
+curl -X POST --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations/$ORGANIZATION_ID/onboarding-portal-links" \
+     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "expires_at": "2025-06-01T00:00:00Z",
+           "enable_sso": true
+         }'
+```
+
+Result:
+
+```json
+{
+  "id": "d36ad207-e1a8-4eac-bc1b-c25e223cc15b",
+  "value": "Fhca7DvuRLjQpDslMpYHMfsqSoy7vbI92PAxNlziZDidGBiW",
+  "project_id": "836b03f7-fdce-466a-9407-8595a0f615ce",
+  "organization_id": "517cc5e7-1ab6-4dcf-ba02-00fad003af92",
+  "enable_sso": true,
+  "created_at": "2025-06-02T05:23:45.299988Z",
+  "expires_at": "2025-06-03T05:23:45Z"
+}
+```
+
+The response contains a `value` token that you can use to construct the onboarding portal link as follows:
+
+`https://your-slug.projects.oryapis.com/onboarding/<value>`
+
+#### Delete an onboarding portal link
+
+```shell
+curl -X DELETE --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations/$ORGANIZATION_ID/onboarding-portal-links/$ONBOARDING_PORTAL_LINK_ID" \
+     -H "Authorization: Bearer $WORKSPACE_API_KEY"
+```
+
+#### List onboarding portal links
+
+```shell
+curl -X GET --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations/$ORGANIZATION_ID/onboarding-portal-links" \
+     -H "Authorization: Bearer $WORKSPACE_API_KEY"
+```
+
+Result:
+
+```json
+{
+  "links": [
+    {
+      "id": "d6458578-dbeb-45ee-95e7-3b98168ff313",
+      "value": "eHSoZlTTffFP76ns0DOqBI8CT2daCXqRqO3MSVFi7eEbaRIu",
+      "project_id": "836b03f7-fdce-466a-9407-8595a0f615ce",
+      "organization_id": "517cc5e7-1ab6-4dcf-ba02-00fad003af92",
+      "enable_sso": true,
+      "created_at": "2025-06-02T05:44:24.883665Z",
+      "expires_at": "2025-06-03T05:44:24Z"
+    }
+  ]
+}
+```
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+```
+
+#### Expiry
+
+The link generated from the Ory Network Console expires in 7 days. The API allows you to set an expiration value with a minimum
+expiry of 1 day. Once the link expires, it no longer works. You can also delete the link and generate a new one.
+
+#### Handover and using the portal
+
+Once you generate the link, share it with the organization's administrator. They can access this link multiple times until its
+expiration to manage (add, edit, or delete) the organization's SSO connections.
+
+```mdx-code-block
+
+<BrowserWindow url="https://<your-slug>.projects.oryapis.com/onboarding/<unique-token>">
+    ![Onboarding portal](./_static/onboarding-portal.png)
+</BrowserWindow>
+```