Sync open source content 🐝 (from 215c13521523a2eb577d94bd21858940f714649b)

Author: beezythebot

docs/ai-control-plane/identity/identities/enterprise-managed-auth.mdx

@@ -56,10 +56,36 @@ Setup happens partly in the dashboard and partly in the Okta Admin Console.
 
 ### Connect Okta
 
+Speakeasy reads apps, users, and groups from Okta through an API service app. There are two ways to set one up:
+
+- **Okta Integration Network.** Install the Speakeasy integration from the Okta catalog. Okta creates the app and gives you a client ID and client secret.
+- **Custom API Services app.** Create the app yourself in Okta. It authenticates with a public key that Speakeasy hosts, so there is no secret to copy.
+
+#### Install from the Okta Integration Network
+
+- In the Okta Admin Console, open **Applications and Resources > API Service Integrations**, select **Add Integration**, and choose **Speakeasy**.
+- Review the read-only permissions for apps, users, and groups, and select **Install & Authorize**.
+- Copy the **Okta domain**, **Client ID**, and **Client secret**. Okta shows the client secret only once.
+- In the dashboard, open [**IDP and SSO > Identity providers**](https://app.getgram.ai/@self/identity?tab=identity-providers) and select **Connect Okta** on the Okta card.
+- Choose **Okta Integration Network (client secret)**, enter the Okta organization URL, such as `https://example.okta.com`, and select **Create connection**.
+- Enter the **Client ID** and **Client secret** and select **Submit and verify**.
+
+The client secret is stored encrypted and never shown again. If you rotate it in Okta, select **Replace client secret** on the connection and enter the new one. If Okta rejects the new secret, the connection keeps the previous one.
+
+#### Create a custom API Services app
+
 - Open [**IDP and SSO > Identity providers**](https://app.getgram.ai/@self/identity?tab=identity-providers) and select **Connect Okta** on the Okta card.
-- Enter the Okta organization URL, such as `https://example.okta.com`, and select **Create connection**.
-- Follow the **Okta setup checklist** in the Okta Admin Console. It walks through creating an API Services app for Speakeasy that authenticates with the public key URL the checklist shows, granting read-only scopes for apps, users, and groups, and assigning read-only admin roles.
-- Paste the app's **Client ID** and select **Submit and verify**.
+- Choose **Custom API Services app (private key)**, enter the Okta organization URL, such as `https://example.okta.com`, and select **Create connection**. The Okta Admin Console address also works.
+- Follow the **Okta setup checklist**, which shows the key URL to use. In the Okta Admin Console:
+  - Open **Applications and Resources > Applications**, choose **Create App Integration**, and select **API Services**. Name the app Speakeasy, choose **Use Okta-generated client ID**, and save it. Do not choose Client ID Metadata Document (CIMD).
+  - On the app's **General** tab, edit **Public keys**, choose **Use a URL to fetch keys dynamically**, and enter the key URL from the checklist.
+  - Under **Client Credentials**, set **Client authentication** to **Public key / Private key**. Okta enables this option only after the key URL is saved; refresh the page if it is still grayed out.
+  - Leave **Require Demonstrating Proof of Possession (DPoP) header in token requests** enabled.
+  - On the **Okta API Scopes** tab, grant `okta.apps.read`, `okta.users.read`, and `okta.groups.read`.
+  - On the **Admin roles** tab, assign **Application Administrator** (org-wide) and **Read-only Administrator**.
+- Paste the app's **Client ID**, which starts with `0oa`, and select **Submit and verify**. The client ID can be saved only once; to change it, revoke the connection and connect again.
+
+#### After connecting
 
 When verification passes, the Okta card shows **Verified** and a **Manage Okta** button.