# Connect Okta

The Okta connection lets Speakeasy read the applications in your Okta org and each application's assignments. It doesn't read your Okta user or group directory. Speakeasy uses it to list your apps, suggest catalog MCP servers that match them, and check Okta setup for [Enterprise Managed Auth](/docs/ai-control-plane/identity/identities/enterprise-managed-auth). It is read-only: Speakeasy never changes anything in your Okta org, and this connection doesn't sign anyone in or issue tokens.

This guide covers the Speakeasy integration in the Okta Integration Network (OIN), which authenticates with a client ID and client secret. If your Okta org doesn't allow client-secret authentication, use a custom API Services app with a private key instead. See [Connect Okta](/docs/ai-control-plane/identity/identities/enterprise-managed-auth/services#1-connect-okta) on the services page.

## Prerequisites

- **A Speakeasy organization** and a Speakeasy user with the `org:admin` scope, which the default [Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions) holds.
- **An Okta administrator** who can install API Service integrations and assign admin roles. A Super Administrator can do both.
- **An Okta org URL** ending in `.okta.com`, `.oktapreview.com`, `.okta-emea.com`, `.okta-gov.com`, or `.okta.mil`. If your org uses a custom domain, enter its Okta address, such as `https://example.okta.com`, instead.

## Supported features

- **Read applications.** Speakeasy lists the apps in your Okta org and shows them on the **Applications** tab, with each app's sign-on method and status.
- **Read app assignments.** For each app, Speakeasy reads the app's assignment list, which records the users and groups assigned to that app, and shows the counts on the **Applications** tab. This is part of the app's data in Okta, so it needs no user or group scope.
- **Suggest MCP servers.** Speakeasy matches your apps against its MCP server catalog and suggests servers for the apps your organization already uses.
- **Check Enterprise Managed Auth setup.** The Cross App Access checklist uses the connection to check that the Okta side is set up.

The integration doesn't support single sign-on, user provisioning, or any change to your Okta org.

## Supported scopes

| Scope            | Used to                                            |
| ---------------- | -------------------------------------------------- |
| `okta.apps.read` | List applications and read each one's assignments. |

Speakeasy doesn't request `okta.users.read` or `okta.groups.read`.

## Configuration steps

### In Okta: install the integration

1. Sign in to the Okta Admin Console as an administrator.
2. Go to **Applications > API Service Integrations** and select **Add Integration**.
3. Select **Speakeasy**.
4. Review the requested scope, `okta.apps.read`, and select **Install & Authorize**.
5. Copy the **Client ID** and **Client secret**. Okta shows the client secret only once, so copy it before leaving the page.

> If Speakeasy later reports that it can't read your apps, open the Speakeasy
> integration's **Admin roles** tab in Okta and assign the **Application
> Administrator** role for all apps and the **Read-only Administrator** role.
> Okta asks you to confirm your identity with multi-factor authentication first.

### In Speakeasy: connect the integration

1. Open [**IDP and SSO > Identity providers**](https://ai.speakeasy.com/@self/identity?tab=identity-providers) and select **Connect Okta**.
2. Enter your Okta org URL, such as `https://example.okta.com`, and select **Continue**. You can also paste your Okta Admin Console address.
3. On the **Setup** tab, choose **Okta Integration Network (client secret)**.
4. Enter the **Client ID** (it starts with `0oa`) and the **Client secret** from Okta, then select **Submit and verify**.

Speakeasy checks that the credentials work, that Okta granted `okta.apps.read`, and that it can read your apps. When the check passes, the Okta card shows **Verified**.

![The Identity providers tab of IDP and SSO, with a verified Okta card and the Manage Okta button](/assets/docs/ai-control-plane/identity/okta-identity-providers.webp)

The client ID can be saved only once. To use a different integration, revoke the connection and connect again.

### Check that it works

1. Select **Manage Okta** and open the **Applications** tab.
2. Select **Update now**. When the update finishes, the tab lists your Okta apps, with the number of users and groups assigned to each.
3. To confirm the data comes from Okta, assign a user or group to one of the apps in Okta, then select **Update now** again. That app's **Users** or **Groups** count goes up.

Speakeasy also updates the list on a schedule, so changes in Okta show up without selecting **Update now**.

## Remove the integration

1. In Speakeasy, open the Okta **Setup** tab and select **Revoke**. Speakeasy deletes the stored client secret and stops reading from Okta.
2. In Okta, go to **Applications > API Service Integrations**, open **Speakeasy**, and remove the integration.

## Troubleshooting

| Message                                                 | Fix                                                                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| The org URL is not accepted                             | Enter the Okta address of your org, ending in one of the domains under [Prerequisites](#prerequisites)      |
| Okta rejected the client ID or client secret.           | Copy both values again from the Speakeasy integration in Okta. Use its client ID, not an SSO app's          |
| Okta did not grant all required permissions (scopes).   | Grant `okta.apps.read` on the integration's **Okta API Scopes** tab in Okta, then select **Re-verify**      |
| Check the app's admin role in Okta.                     | Assign the admin roles in the callout under [In Okta](#in-okta-install-the-integration), then **Re-verify** |
| Speakeasy could not read applications from Okta.        | Check the admin roles, then select **Re-verify**                                                            |
| Okta could not be reached during the last verification. | Check the org URL and try **Re-verify** again                                                               |

For help, contact [Speakeasy support](https://www.speakeasy.com/contact).

---

Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.