@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/integrations/salesforce-oauth.mdx

@@ -0,0 +1,116 @@
+---
+title: Salesforce OAuth
+description: Learn how to set up OAuth with Salesforce.
+icon: salesforce
+breadcrumb:
+  title: Integrations
+  url: /integrations
+originalPath: .tmp-workos-clone/packages/docs/content/integrations/salesforce-oauth.mdx
+---
+
+## Introduction
+
+The Salesforce OAuth integration allows your users to authenticate using their Salesforce credentials.
+
+The configuration process involves creating an External Client App in Salesforce and configuring the client credentials in the WorkOS Dashboard.
+
+---
+
+## What WorkOS provides
+
+When setting up Salesforce OAuth, WorkOS provides one key piece of information that needs to be configured in your Salesforce External Client App:
+
+- [Redirect URI](/glossary/redirect-uri): The endpoint where Salesforce will send authentication responses after successful login
+
+The Redirect URI is available in the [WorkOS Dashboard](https://dashboard.workos.com/). In the left navigation menu, select the **Authentication** tab and the **OAuth providers** sub-tab. Locate the **Salesforce** section.
+
+![Open the Salesforce configuration dialog](https://images.workoscdn.com/images/27840df3-434d-4fc0-bae3-aa3dee021f2a.png?auto=format&fit=clip&q=50)
+
+Click **Manage**. The **Salesforce OAuth** configuration dialog will open. Locate the **Redirect URI**.
+
+![Salesforce OAuth Redirect URI in the WorkOS Dashboard](https://images.workoscdn.com/images/387b564f-7c4c-4b94-aece-7dc3eb862058.png?auto=format&fit=clip&q=50)
+
+The **Redirect URI** serves as the destination for authentication responses and must be configured in your Salesforce External Client App as the authorization callback URL.
+
+---
+
+## What you'll need
+
+You will need to obtain two pieces of information from a Salesforce External Client App:
+
+- **Salesforce Consumer Key**: Application identifier from Salesforce
+- **Salesforce Consumer Secret**: Authentication secret for the application
+
+The following sections will guide you through creating an External Client App in your Salesforce instance and generating these credentials.
+
+---
+
+## (1) Create the Salesforce External Client App
+
+Sign in to Salesforce and navigate to Setup. On the sidebar, select **Apps**, then **External Client Apps**, then **External Client App Manager**. Create a new External Client App.
+
+![The New External Client App button in Salesforce](https://images.workoscdn.com/images/e17fec69-13b5-4281-8311-5854ac1007af.png?auto=format&fit=clip&q=50)
+
+---
+
+## (2) Configure External Client App
+
+Fill out the External Client App form. Expand the **API (Enable OAuth Settings)** section, and check the **Enable OAuth** checkbox. For the **Callback URL** input, enter the **Redirect URI** from the WorkOS Dashboard.
+
+It is also required to add the "Access the identity URL service" and "Access unique user identifiers" scopes to your app.
+
+![The Salesforce form to create a new External Client App](https://images.workoscdn.com/images/f1ce3367-fc4f-4be6-9529-49835431c38e.png?auto=format&fit=clip&q=50)
+
+Under **Security** deselect the **Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows** option, as WorkOS does not currently support PKCE for Salesforce OAuth.
+
+Click **Create**.
+
+![The option to disable the PCKE requirement for a Salesforce External Client App](https://images.workoscdn.com/images/7e9a2bda-0ba4-4d33-a5f4-3ae07909a67e.png?auto=format&fit=clip&q=50)
+
+After creating your External Client App, click the **Settings** tab, and then expand **OAuth Settings**. Click on **Consumer Key and Secret**.
+
+You'll be given the Consumer Key and Secret for your External Client App. Note these values as you'll need them for the WorkOS configuration.
+
+---
+
+## (3) Configure Salesforce credentials in WorkOS
+
+Now that you have the **Salesforce Consumer Key** and **Salesforce Consumer Secret** from the previous step return to the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+In the **Salesforce OAuth** configuration dialog, paste the credentials from Salesforce into the Client ID and Client Secret fields.
+
+![Where to enter the Salesforce Consumer Key and Salesforce Consumer Secret in the WorkOS Dashboard](https://images.workoscdn.com/images/f65f7819-f9c9-4321-9ba5-9365fa51f4e8.png?auto=format&fit=clip&q=50)
+
+Click **Save changes** to complete the configuration.
+
+You're now able to authenticate users with Salesforce OAuth. If you are using AuthKit's [Hosted UI](/authkit/hosted-ui), the Login with Salesforce button will be added to your login page.
+
+If you are building your own authentication flows outside of AuthKit's hosted UI, you will use the `provider` query parameter in the [Get Authorization URL API endpoint](/reference/authkit/authentication/get-authorization-url) to support global Salesforce OAuth for any domain. The `provider` query parameter should be set to `SalesforceOAuth`.
+
+---
+
+## Configure Additional OAuth Scopes (Optional)
+
+WorkOS will request the OAuth scopes that are required for authentication by default. You can optionally configure your integration to request additional OAuth scopes as needed.
+
+When the **Return Salesforce OAuth tokens** option is selected, the access token from Salesforce will be included in the response from the [Authenticate with code API](/reference/authkit/authentication/code).
+
+![A screenshot showing Salesforce OAuth scopes configuration in the WorkOS Dashboard](https://images.workoscdn.com/images/f1a87bc5-71b3-48fb-b2cf-3052ee39d4b4.png?auto=format&fit=clip&q=50)
+
+Any scopes configured here will be included on every Salesforce OAuth request. To specify additional scopes dynamically, use the `provider_scopes` query parameter on the [Get Authorization URL API endpoint](/reference/authkit/authentication/get-authorization-url). You will also have to update your External Client App's configured scopes to include these additional scopes.
+
+For more information, see Salesforce's OAuth scopes [documentation](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_tokens_scopes.htm).
+
+## Frequently asked questions
+
+### How is the WorkOS Salesforce OAuth integration different from implementing regular Salesforce OAuth flow?
+
+It's the same Salesforce OAuth flow as you could build yourself, but it's encapsulated within WorkOS SSO. This means you don't need to build it yourself. In addition to Salesforce OAuth, you can use WorkOS SSO to support other identity providers, all with a single integration.
+
+### What is the provider query parameter and how is it used in the Salesforce OAuth integration?
+
+You can use the `provider` query parameter in the [Get Authorization URL API endpoint](/reference/authkit/authentication/get-authorization-url) to support global Salesforce OAuth for any domain. The `provider` query parameter should be set to `SalesforceOAuth`.
+
+### What scopes are required for Salesforce OAuth?
+
+The **openid**, **profile**, and **email** scopes are required to allow the application to read user profile information necessary for authentication. These scopes provide access to the user's basic profile data.

package/.docs/organized/docs/integrations/salesforce-saml.mdx

@@ -1,6 +1,6 @@
 ---
-title: Salesforce
-description: "Learn how to configure a connection to\_Salesforce via SAML."
+title: Salesforce SAML
+description: Learn how to configure a connection to Salesforce via SAML.
 icon: salesforce
 breadcrumb:
   title: Integrations
@@ -86,7 +86,7 @@ Give the App and API a meaningful name and set a contact email that corresponds
 
 Scroll down further to the “Web App Settings” and check the box for “Enable SAML”. Enter the Entity ID and ACS URL into their respective places within the Settings.
 
-The “Subject Type” should be set to “User ID” and the “Name ID Format” should be set to `urn:oasis:names:tv:SAML:1.1:nameid-format:emailAddress`. The “Issuer” should populate correctly with your Salesforce subdomain. For the IdP Certificate, select the certificate that matches the one previously used when enabling the Identity Provider, and for the “Signing Algorithm for SAML Messages” choose “SHA256”.
+The “Subject Type” should be set to “User ID” and the “Name ID Format” should be set to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. The “Issuer” should populate correctly with your Salesforce subdomain. For the IdP Certificate, select the certificate that matches the one previously used when enabling the Identity Provider, and for the “Signing Algorithm for SAML Messages” choose “SHA256”.
 
 ![A screenshot showing how to configure the Connected App's Web App Settings in the Salesforce Dashboard.](https://images.workoscdn.com/images/98390601-4c8a-42f4-9965-52ddcd28ff45.png?auto=format&fit=clip&q=50)
 
@@ -120,7 +120,7 @@ With [identity provider role assignment](/sso/identity-provider-role-assignment)
 
 ![A screenshot showing where to add the groups attribute in the Salesforce dashboard.](https://images.workoscdn.com/images/0f2abfab-25c9-4ce4-aeb4-7f0f3fae8038.png?auto=format&fit=clip&q=50)
 
-> Finish role assignment set-up by navigating to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the group IdP ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
+> Finish role assignment set-up by navigating to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the IdP Group ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
 
 ---
 

package/.docs/organized/docs/integrations/saml.mdx

@@ -1,6 +1,6 @@
 ---
 title: SAML
-description: Learn how to configure a new custom SAML connection.
+description: Learn how to configure a new custom SAML connection
 breadcrumb:
   title: Integrations
   url: /integrations
@@ -9,56 +9,76 @@ originalPath: .tmp-workos-clone/packages/docs/content/integrations/saml.mdx
 
 ## Introduction
 
-Each SSO Identity Provider requires specific information to create and configure a new [Connection](/glossary/connection). Often, the information required to create a Connection will differ by Identity Provider.
-
-To create a custom SAML Connection, you’ll need the Identity Provider Metadata URL that is available from the organization's SAML instance.
+To set up a SAML connection on behalf of an organization, you'll need the identity provider metadata or manual configuration details from the organization's IT team.
 
 ---
 
 ## What WorkOS provides
 
-WorkOS provides the [ACS URL](/glossary/acs-url), the [SP Entity ID](/glossary/sp-entity-id), and the [SP Metadata](/glossary/sp-metadata) link. They are readily available in your Connection Settings in the [WorkOS Dashboard](https://dashboard.workos.com/).
+When setting up a SAML connection, WorkOS provides three key pieces of information in the **Service Provider Details** section for an SSO connection within the [WorkOS Dashboard](https://dashboard.workos.com/):
+
+- [SP Entity ID](/glossary/sp-entity-id): A unique identifier that represents your application in SAML communications
+- [ACS URL](/glossary/acs-url): The endpoint where identity providers send authentication responses
+- [SP Metadata](/glossary/sp-metadata): A configuration file containing all necessary SAML settings
 
-![WorkOS Settings](https://images.workoscdn.com/images/3c27f5a8-ee88-4b7f-9659-0db9b80dea70.png?auto=format&fit=clip&q=50)
+![WorkOS Settings](https://images.workoscdn.com/images/bc0ebb05-e918-4217-8435-bfd1c73dd1f6.png?auto=format&fit=clip&q=80)
 
-The ACS URL is the location an Identity Provider redirects its authentication response to. The SP Entity ID is a URI used to identify the issuer of a SAML request and the audience of a SAML response. The SP Metadata link contains a metadata file that the organization can use to set up the SAML integration.
+These settings are required to configure a SAML integration. The **ACS URL** serves as the destination for authentication responses, while the **SP Entity ID** uniquely identifies your application in SAML requests and responses. The **SP Metadata** URL provides a complete configuration file that simplifies the setup process for the organization.
 
 ---
 
-## What you’ll need
+## What you will need
+
+You will need to obtain one of the following from the organization:
 
-In order to integrate you’ll need the IdP Metadata URL.
+- [Identity Provider Metadata URL](/glossary/idp-metadata): Configuration URL containing SAML metadata (preferred)
+- Manual configuration details: SSO URL, Entity ID, and X.509 Certificate (if metadata URL is not available)
 
-Normally, this information will come from the organization's IT Management team when they set up your application’s SAML 2.0 configuration in their Identity Provider admin dashboard. But, should that not be the case during your setup, here’s how to obtain them.
+Typically, the organization's IT team will provide these values when they configure your application in their identity provider admin dashboard. However, if you need to guide them through the process, the following sections will help.
 
 ---
 
-## (1) Enter Service Provider Details
+## (1) Configure Service Provider Details
+
+For SSO to properly function, the organization needs to create and configure a SAML application in their identity provider.
+
+Copy the **ACS URL** and **SP Entity ID** from the **Service Provider Details** section in the WorkOS Dashboard.
 
-Copy and Paste the “ACS URL” and “SP Entity ID” into the corresponding fields for Service Provider details and configuration. For some SAML setups, you can use the metadata found at the SP Metadata link to configure the SAML connection.
+Instruct the organization admin to paste these values into the corresponding fields in their identity provider's admin dashboard. Alternatively, they can use the service provider metadata URL to automatically configure the SAML connection if their identity provider supports metadata-based configuration.
 
 ---
 
-## (2) Obtain Identity Provider Metadata
+## (2) Obtain identity provider metadata
 
-Copy the IdP Metadata URL from your SAML settings and upload it to your WorkOS Connection settings. Your Connection will then be linked and good to go!
+After the organization creates a SAML application, their identity provider will provide either a metadata URL or manual configuration details.
 
-![Upload IdP Metadata URL to WorkOS Dashboard](https://images.workoscdn.com/images/9a3498b2-eeb8-4ecf-b2f3-c3ed41d081cb.png?auto=format&fit=clip&q=50)
+If they have a metadata URL, in the WorkOS Dashboard, navigate to the **Identity Provider Configuration** section. Click **Edit Configuration**.
 
-Some SAML providers might not be able to provide the IdP Metadata URL. In these cases, you’ll want to manually configure the connection.
+![Open Identity Provider Configuration in WorkOS Dashboard](https://images.workoscdn.com/images/a33cc226-7167-4450-8879-9f123fc8ffeb.png?auto=format&fit=clip&q=80)
 
-![Switch to Manual Configuration](https://images.workoscdn.com/images/2e8f0c39-986b-4529-bacc-2e1843be4842.png?auto=format&fit=clip&q=50)
+Paste the metadata URL from the organization's IT team into the input field. Your connection will be automatically configured once the metadata is processed.
 
-![Manually Configure Connection in WorkOS Dashboard](https://images.workoscdn.com/images/880ce675-48d5-4b49-9871-1cf4b38d1a10.png?auto=format&fit=clip&q=50)
+![Upload identity provider metadata URL to WorkOS Dashboard](https://images.workoscdn.com/images/4d25d1a1-57a0-464d-95d7-a33eb85d2e0f.png?auto=format&fit=clip&q=80)
+
+If the organization's identity provider doesn't provide a metadata URL, you'll need to manually configure the connection by clicking the **Switch to Manual Configuration** option and entering the SSO URL, Entity ID, and X.509 Certificate provided by their IT team.
+
+![Switch to Manual Configuration](https://images.workoscdn.com/images/7384d9b7-b918-4778-ac1f-2b389cf73241.png?auto=format&fit=clip&q=80)
+
+![Manually configure connection in WorkOS Dashboard](https://images.workoscdn.com/images/37eaf62e-dd9f-41b0-9e91-221256318298.png?auto=format&fit=clip&q=80)
 
 ---
 
-## (3) Configure Attribute Mapping
+## (3) Configure attribute mapping
+
+The organization's SAML provider needs to include specific attributes in the SAML response. Instruct them to configure their SAML application to include the following attributes in the Attribute Statement:
 
-At a minimum, the Attribute Statement in the SAML Response should include `id`, `email`, `firstName`, and `lastName` attributes.
+- `id`: Maps to the `idp_id` attribute in WorkOS user profiles
+- `email`: Maps to the `email` attribute in WorkOS user profiles
+- `firstName`: Maps to the `first_name` attribute in WorkOS user profiles
+- `lastName`: Maps to the `last_name` attribute in WorkOS user profiles
 
-### Role Assignment (optional)
+### Role assignment (optional)
 
-With [identity provider role assignment](/sso/identity-provider-role-assignment), users can receive roles within your application based on their group memberships. To return this information in the attribute statement, map the groups in your identity provider to a SAML attribute named `groups`.
+With [identity provider role assignment](/sso/identity-provider-role-assignment), users can receive roles within your application based on their group memberships. To enable this functionality, instruct the organization to add a `groups` attribute to the SAML response that maps to a list of the user's group memberships.
 
-Once your SAML app is configured to return groups, navigate to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the group IdP ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
+> Finish role assignment set-up by navigating to the SSO connection page in the **Organizations** section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the IdP Group ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.

package/.docs/organized/docs/integrations/scim.mdx

@@ -1,6 +1,6 @@
 ---
 title: SCIM
-description: "Learn about syncing your user list with\_a\_custom SCIM provider."
+description: Learn about syncing users with a custom SCIM provider
 breadcrumb:
   title: Integrations
   url: /integrations
@@ -9,56 +9,68 @@ originalPath: .tmp-workos-clone/packages/docs/content/integrations/scim.mdx
 
 ## Introduction
 
-This guide outlines how to synchronize your application’s user and group directories using SCIM v2.0.
+To set up a SCIM v2.0 directory sync connection, you'll need to provide the organization’s IT team with specific configuration details from WorkOS. This allows their SCIM server to synchronize users and groups with your application.
 
-To synchronize an organization’s users and groups provisioned for your application, you’ll need to provide the organization with two pieces of information:
+---
+
+## What WorkOS provides
+
+When setting up a SCIM directory sync connection, WorkOS provides two key pieces of information that you'll need to share with the organization:
+
+- [Endpoint](/glossary/endpoint): The URL where the SCIM server will send requests
+- [Bearer Token](/glossary/bearer-token): Authentication credentials for the endpoint requests
+
+Both of these are available in the **Directory details** section of the directory sync connection in the [WorkOS Dashboard](https://dashboard.workos.com/).
 
-- An [Endpoint](/glossary/endpoint) that the SCIM server will make requests to.
-- A [Bearer Token](/glossary/bearer-token) to authenticate its endpoint requests.
+![The WorkOS dashboard, highlights the directory details card with filled endpoint and bearer token inputs](https://images.workoscdn.com/images/1ae8c088-07d6-4512-9abf-1adec38f6b0b.png?auto=format&fit=clip&q=50)
 
-Both of these are available in your Endpoint’s Settings in the [WorkOS Dashboard](https://dashboard.workos.com/).
+These settings enable the organization’s SCIM server to securely send user and group data to your application through WorkOS.
 
 ---
 
-## (1) Set up your directory sync endpoint
+## What you will need
+
+The organization’s IT team will handle the SCIM server configuration on their end. You simply need to provide them with the endpoint URL and bearer token from the WorkOS Dashboard.
 
-Login to your WorkOS dashboard and select “Organizations” from the left hand Navigation bar.
+Typically, the organization's IT team will use these values to configure your application within their SCIM server or identity provider admin dashboard.
 
-Select the Organization you’d like to enable a SCIM Directory Sync connection for.
+---
+
+## (1) Set up your directory sync endpoint
 
-On the Organization’s page go to "Actions" and then click “Add Directory”.
+Login to the [WorkOS Dashboard](https://dashboard.workos.com/).
 
-![A screenshot showing where to find “Add Directory” in the WorkOS Dashboard.](https://images.workoscdn.com/images/4fdc6225-8233-4f5b-9361-d99f0ad5ae6f.png?auto=format&fit=clip&q=50)
+In the left navigation menu, select the **Organizations** tab. Select the appropriate organization for which you will enable a SCIM directory sync connection.
 
-Select “Custom SCIM v2.0” as the directory type, and then input the Company Name.
+On the organization’s page, scroll down to the **Directory Sync** section. Click **Configure manually**.
 
-Click the “Create Directory” button.
+![WorkOS Dashboard showing directory sync card with configure manually button highlighted](https://images.workoscdn.com/images/ebf08eb3-a698-4498-adde-1b551ab0f519.png?auto=format&fit=clip&q=50)
 
-![A screenshot showing "Create Directory" details in the WorkOS Dashboard.](https://images.workoscdn.com/images/a1432401-3eed-475a-b4b0-1ea18840be9a.png?auto=format&fit=clip&q=50)
+Select **Custom SCIM v2.0** as the directory type. Input an appropriate name for the connection. Click **Create Directory**.
 
-The Directory Sync Connection will now display the Endpoint for the SCIM server to send requests to, and the Bearer Token.
+![The WorkOS Dashboard with a create directory dialog showing directory type and name inputs](https://images.workoscdn.com/images/aa5a17d9-0990-4af6-a61f-1640658650e1.png?auto=format&fit=clip&q=50)
 
-![A screenshot showing where to find the Endpoint and Bearer Token for an organization in the WorkOS Dashboard.](https://images.workoscdn.com/images/0ab40cc6-3374-4032-9f33-91a36554db29.png?auto=format&fit=clip&q=50)
+The directory sync connection will now display the endpoint for the SCIM server and the bearer token.
 
-> We have support for custom labeled URLs for Directory Sync endpoints. [Contact us](mailto:support@workos.com) for more info!
+> We have support for custom labeled URLs for directory sync endpoints. [Contact us](mailto:support@workos.com) for more info!
 
 ---
 
-## (2) Configure the SCIM server integration
+## (2) Provide SCIM configuration to the organization
 
-WorkOS provides you with all of the relevant information for an organization to plug and play SCIM functionality for your application.
+Copy the **Endpoint** and **Bearer Token** from the **Directory details** section on the directory page of the WorkOS Dashboard.
 
-Provide the organization with:
+Provide these values to the organization’s IT team so they can configure the application within their SCIM server or identity provider admin dashboard:
 
-- The Endpoint from your [WorkOS Dashboard](https://dashboard.workos.com/), and
-- The Bearer Token from your [WorkOS Dashboard](https://dashboard.workos.com/).
+- **Endpoint URL**: The destination where their SCIM server will send user and group data
+- **Bearer Token**: Authentication credentials for secure communication
 
-Once the organization has used these values to configure your application within their SCIM server, then your application is ready to synchronize users and groups.
+Once the organization has configured these values in their SCIM server, your application will be ready to receive real-time user and group synchronization.
 
 ---
 
 ## (3) Assign users and groups to your application
 
-Now, whenever the organization assigns users or groups to your application, you’ll receive realtime Dashboard updates based on changes in their directory.
+Now, whenever the organization assigns users or groups to your application in their directory, you’ll receive real-time dashboard updates based on changes in their system.
 
 A detailed guide to integrate the WorkOS API with your application can be found [here](/directory-sync)

package/.docs/organized/docs/integrations/sftp.mdx

@@ -1,6 +1,6 @@
 ---
 title: SFTP
-description: "Learn about syncing your user list using an\_SFTP\_connection."
+description: Learn about syncing users with an SFTP connection
 breadcrumb:
   title: Integrations
   url: /integrations
@@ -9,11 +9,11 @@ originalPath: .tmp-workos-clone/packages/docs/content/integrations/sftp.mdx
 
 ## Introduction
 
-An SFTP integration allows an organization to synchronize user and group information by uploading CSV files using SFTP.
-WorkOS maintains a receiving SFTP server that can be connected to from the organization's HRIS provider/SFTP client.
+To set up an SFTP (Secure File Transfer Protocol) directory sync connection, you'll need to provide the organization's IT team with specific configuration details from WorkOS. This allows them to upload CSV files containing user and group information via SFTP.
 
-If the organization's HRIS has a built-in SFTP client, SFTP will allow them to automatically sync their data and ensure your data is always up to date.
-An SFTP integration allows for provider-agnostic ingestion of employee data into your product ecosystem.
+WorkOS maintains a receiving SFTP server that the organization's HRIS provider or SFTP client can connect to.
+
+If the organization's HRIS has a built-in SFTP client, SFTP will allow them to automatically sync their data and ensure their data is always up to date. An SFTP integration allows for provider-agnostic ingestion of employee data into your product ecosystem.
 
 Once the integration is set up, WorkOS automatically creates and hosts an SFTP folder for the organization's HRIS provider to upload files at a regular cadence.
 
@@ -23,27 +23,36 @@ An SFTP integration has the following advantages:
 - Has an easy integration path for an organization comfortable working with CSVs and SFTP
 - Allows a custom cadence of updates for your customer
 
-Your app interfaces with an SFTP directory the same as with other directories; receiving [events](/events) when the directory is created or updated:
+Your application interfaces with an SFTP directory the same as with other directories; receiving [events](/events) when the directory is created or updated:
 
 <DirectorySyncDiagram.SftpDirectoryActivated />
 
-> Note: The SFTP integration isn't enabled by default in the WorkOS Dashboard or Admin Portal. Please reach out to [support@workos.com](mailto:support@workos.com) or via your team’s WorkOS Slack channel if you would like SFTP enabled.
-
 ---
 
 ## What WorkOS provides
 
-WorkOS provides an SFTP server URL and username specific to the directory. Once set up, the URL and username will be available under directory settings in the [WorkOS Dashboard](https://dashboard.workos.com/).
+When setting up an SFTP directory sync connection, WorkOS provides two key pieces of information that you'll need to share with the organization:
+
+- **SFTP Server URL**: The location where the organization will upload user and group CSV files
+- **Username**: Authentication credentials for SFTP access
+
+These are available in your directory’s settings in the [WorkOS Dashboard](https://dashboard.workos.com/) once the connection is configured.
+
+![SFTP directory details in the WorkOS Dashboard.](https://images.workoscdn.com/images/46c63f08-579e-4e60-8cb6-b20d6f95ff8b.png?auto=format&fit=clip&q=50)
 
-The SFTP URL is the location of the SFTP server to upload user and group information. Authentication uses a username and a key pair.
+The SFTP server uses public key authentication, providing secure file transfer capabilities for user and group data synchronization.
 
 ---
 
 ## What you will need
 
-You will need to provide a public key for authentication. Normally this will come from a key pair provided your customer’s IT team and may be created by their HRIS. Maximum key length is 2048 bytes and supported keys are: `ED25519`, `RSA`, and `ECDSA`.
+The organization will need to provide a public key for authentication and prepare their user and group data in the required CSV format.
 
-Your customer will need to export the users and groups as CSV files with the structure below.
+You will need to obtain from the organization:
+
+- **Public Key**: For SFTP authentication (maximum key length is 2048 bytes; supported keys are: `ED25519`, `RSA`, and `ECDSA`)
+
+The organization will need to export their users and groups as CSV files with the structure below.
 
 ### `users.csv`
 
@@ -53,13 +62,13 @@ This file is required.
 
 ### `user_groups.csv`
 
-This file is required.
+This file is _optional_.
 
 <DirectorySyncCsvSchemaTable.UserGroups />
 
 ### `groups.csv`
 
-This file is _not_ required. Additional metadata may be also included in this file.
+This file is _optional_. Additional metadata may be also included in this file.
 
 <DirectorySyncCsvSchemaTable.Groups />
 
@@ -67,49 +76,63 @@ This file is _not_ required. Additional metadata may be also included in this fi
 
 ## (1) Set up your directory sync endpoint
 
-Login to your WorkOS Dashboard and select “Organizations” from the left hand navigation bar. Select the organization you’ll be configuring a new Directory Sync connection with.
+Login to the [WorkOS Dashboard](https://dashboard.workos.com/).
 
-Click “Add Directory”. Select “SFTP” as the directory type, and then enter a name for this directory.
+In the left navigation menu, select the **Organizations** tab. Select the appropriate organization for which you will enable a SFTP directory sync connection.
 
-Click “Create Directory”.
+On the organization's page, scroll down to the **Directory Sync** section. Click **Configure manually**.
 
-![A screenshot showing how to create a directory in the WorkOS Dashboard.](https://images.workoscdn.com/images/b427dceb-7a05-4593-9598-d2fccaf3da4f.png?auto=format&fit=clip&q=100)
+![WorkOS Dashboard showing directory sync card with configure manually button highlighted](https://images.workoscdn.com/images/ebf08eb3-a698-4498-adde-1b551ab0f519.png?auto=format&fit=clip&q=50)
 
-## (2) Enter the customer’s public key
+Select **SFTP** as the directory type. Input an appropriate name for the connection. Click **Create Directory**.
 
-Retrieve the public key that will be used for SFTP from the organization’s admin.
+![The WorkOS Dashboard with a create directory dialog](https://images.workoscdn.com/images/e1010105-9c22-4d20-88d0-8b316df97ad2.png?auto=format&fit=clip&q=50)
+
+---
 
-Click “Update Directory” in the WorkOS Dashboard.
+## (2) Configure SFTP authentication
 
-![A screenshot showing where to find "Update directory" for an Organization in the WorkOS Dashboard.](https://images.workoscdn.com/images/0967a645-2e54-4e9d-a197-e8177d23cc76.png?auto=format&fit=clip&q=100)
+Obtain the public key from the organization’s admin that will be used for SFTP authentication.
 
-Enter the customer’s public key in the input field.
+From the directory page in the WorkOS Dashboard, in the **Directory details** section click the **Update Directory** button.
+
+![A screenshot showing where to find "Update directory" for an Organization in the WorkOS Dashboard.](https://images.workoscdn.com/images/d0847fd0-b9c9-4ec2-aa1e-b69c6aac1fa5.png?auto=format&fit=clip&q=50)
+
+Paste the organization's public key into the input field.
 
 The SSH public key format should include the key type (e.g. `ssh-rsa`, `ssh-ed25519`), base64 encoded body, and an optional comment, with spaces between each element. For example, `ssh-rsa AAAABB1 keycomment`.
 
-RSA, ECDSA, and ED25519 keys are accepted.
+RSA, ECDSA, and ED25519 keys are accepted:
 
 - For RSA keys, the key type is `ssh-rsa`.
 - For ED25519 keys, the key type is `ssh-ed25519`.
 - For ECDSA keys, the key type is either `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, or `ecdsa-sha2-nistp521`, depending on the size of the key generated.
 
-![A screenshot showing how to update SFTP directory details in the WorkOS Dashboard.](https://images.workoscdn.com/images/14f27355-a6c3-4a5f-a4cc-6e6b392c42d4.png?auto=format&fit=clip&q=100)
+![A screenshot showing how to update SFTP directory details in the WorkOS Dashboard.](https://images.workoscdn.com/images/77a535f1-87d4-410f-bd7c-09a4535e53c2.png?auto=format&fit=clip&q=50)
 
-## (3) Share SFTP details with your customer
+---
 
-After adding the public key, WorkOS generates a username. You will see the green “Linked” icon appear.
+## (3) Provide SFTP configuration to the organization
 
-![A screenshot showing SFTP directory details in the WorkOS Dashboard.](https://images.workoscdn.com/images/aeea5065-5de1-4eb8-96f0-c67f12ddc46a.png?auto=format&fit=clip&q=100)
+After adding the public key, WorkOS generates a username. You will see the green **Linked** icon appear.
 
-Share the username with the organization admin and ask them to upload the CSV files using their private key to `sftp.workos.com`.
+Copy the **Username** and SFTP server URL from the WorkOS Dashboard.
 
-## (4) Confirm users and groups are synced
+Share these values with the organization so they can configure their SFTP client:
+
+- **SFTP Server**: `sftp.workos.com`
+- **Username**: The generated username from the WorkOS Dashboard
+- **Authentication**: Their private key (corresponding to the public key you uploaded)
 
-Now, whenever your customer assigns users or groups to your application, you’ll receive updates based on the changes in their directory.
+Instruct the organization to upload their CSV files using these credentials.
+
+---
+
+## (4) Confirm users and groups are synced
 
-Click on the “Users” tab in the dashboard to view synced users.
+Now, whenever your customer uploads updated CSV files via SFTP, you’ll receive updates based on the changes in their directory data.
 
-![A screenshot showing a synced directory in the WorkOS Dashboard](https://images.workoscdn.com/images/06b6c694-2558-451d-8305-372a43ac3d46.png?auto=format&fit=clip&q=100)
+The **Users** tab within the SFTP connection displays synced users.
 
 A detailed guide to integrate the WorkOS API with your application can be found [here](/directory-sync)
 
@@ -117,9 +140,9 @@ A detailed guide to integrate the WorkOS API with your application can be found
 
 ### How is my organization’s data protected in transit?
 
-SFTP (Secure File Transfer Protocol) uses SSH (Secure Shell protocol) to symmetrically encrypt traffic after an asymmetric key negotiation for authentication.
+SFTP uses SSH (Secure Shell protocol) to symmetrically encrypt traffic after an asymmetric key negotiation for authentication.
 
-Our solution leverages The [AWS Transfer Family](https://docs.aws.amazon.com/transfer/latest/userguide/how-aws-transfer-works.html) so that we can support a common, secure protocol (SSH) with modern, isolated data storage (AWS S3).
+Our solution leverages the [AWS Transfer Family](https://docs.aws.amazon.com/transfer/latest/userguide/how-aws-transfer-works.html), so that we can support a common, secure protocol (SSH) with modern, isolated data storage (AWS S3).
 
 We leverage the default security policy ([security-policy-transfer-2020-06](https://docs.aws.amazon.com/transfer/latest/userguide/security-policies.html#security-policy-transfer-2020-06)) for the choice of SSH cipher-suites, which determines the strength of cryptographic protection for data in transit.
 
@@ -130,7 +153,7 @@ The symmetric encryption used is AES-256, more information is available in [the
 
 ### How does WorkOS isolate one of my organization’s data from the other?
 
-Each of the organizations you’re onboarding will [create an SSH key pair](/integrations/sftp/what-you-will-need), this consists of a public key, and a private key. They will retain the private key, ensuring that only they can authenticate. The public key uploaded to WorkOS will be used to authenticate the organization's connection via SFTP.
+Each of the organizations you onboard will [create an SSH key pair](/integrations/sftp/what-you-will-need), this consists of a public key, and a private key. They will retain the private key, ensuring that only they can authenticate. The public key uploaded to WorkOS will be used to authenticate the organization's connection via SFTP.
 
 Each of your organizations is mapped to a distinct S3 bucket based on an internal (cryptographically random) identifier for the SSH key pair.
 

package/.docs/organized/docs/integrations/shibboleth-generic-saml.mdx

@@ -69,7 +69,7 @@ At a minimum, the Attribute Statement in the SAML Response should include `id`,
 
 With [identity provider role assignment](/sso/identity-provider-role-assignment), users can receive roles within your application based on their group memberships. To return this information in the attribute statement, map the groups in your identity provider to a SAML attribute named `groups`.
 
-Once your SAML app is configured to return groups, navigate to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the group IdP ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
+Once your SAML app is configured to return groups, navigate to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the IdP Group ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
 
 ---
 

package/.docs/organized/docs/integrations/shibboleth-unsolicited-saml.mdx

@@ -69,7 +69,7 @@ At a minimum, the Attribute Statement in the SAML Response should include `id`,
 
 With [identity provider role assignment](/sso/identity-provider-role-assignment), users can receive roles within your application based on their group memberships. To return this information in the attribute statement, map the groups in your identity provider to a SAML attribute named `groups`.
 
-> Finish role assignment set-up by navigating to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the group IdP ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
+> Finish role assignment set-up by navigating to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the IdP Group ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
 
 ---
 

package/.docs/organized/docs/integrations/simple-saml-php.mdx

@@ -1,6 +1,6 @@
 ---
 title: SimpleSAMLphp
-description: "Learn how to configure a\_SimpleSAMLphp connection."
+description: Learn how to configure a SimpleSAMLphp connection.
 icon: simple-saml-php
 breadcrumb:
   title: Integrations
@@ -59,7 +59,7 @@ Ensure the following attribute mapping is set:
 
 With [identity provider role assignment](/sso/identity-provider-role-assignment), users can receive roles within your application based on their group memberships. To return this information in the attribute statement, map the groups in your identity provider to a SAML attribute named `groups`.
 
-> Finish role assignment set-up by navigating to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the group IdP ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
+> Finish role assignment set-up by navigating to the SSO connection page in the _Organization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the IdP Group ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.
 
 ---