> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up SCIM Provisioning in Okta

> Let Okta add, update and remove people in your Searchable workspace, and set their roles from Okta groups

## Overview

SCIM lets Okta manage who belongs to your Searchable workspace. Assign someone to the SCIM app in Okta and they're added to your workspace; unassign or deactivate them and they're removed. If you push Okta groups, Searchable can also set each person's role from their groups.

SSO decides whether someone can sign in. SCIM decides who should have access at all, and tells Searchable as soon as that changes.

> [!NOTE]
>
> SCIM is set up together with the Searchable team. We issue your SCIM token and map your Okta groups
> to roles; you create the SCIM app in Okta and choose who to assign. Contact [support@searchable.com](mailto:support@searchable.com)
> to get started.

## Prerequisites

* Your workspace has a **live** SSO connection to Okta, with your email domains verified. A SCIM token can only be issued once SSO is turned on.
* You're an Okta admin who can create app integrations and assign people to them.
* A Searchable SCIM token and the endpoint URL, which we send you (step 1 below).

## Quick setup

**1. Get your SCIM token and endpoint URL**

Ask [support@searchable.com](mailto:support@searchable.com) for a SCIM token for your workspace. We send you two values:

* **Endpoint URL**: `https://app.searchable.com/api/scim/v2`. Use exactly the URL we send, not a custom domain.
* **SCIM token**: shown to us once, when it's created. Store it in your password manager; if it's lost, we issue a new one.

Each token belongs to one workspace's SSO connection. People Okta pushes with that token join that workspace and no other.

**2. Create a SCIM app in Okta**

In the Okta Admin Console, go to **Applications → Applications**, click **Create App Integration**, and choose **SAML 2.0** as the sign-in method. Give it a name such as "Searchable SCIM".

This app is only used to push people to Searchable; your team keeps signing in through your existing Searchable SSO app. Okta still asks for SAML settings before it saves the app, but they aren't used. Our own test app uses `https://app.searchable.com` for the single sign-on URL and `searchable-scim` for the audience.

On the new app's **General** tab, click **Edit** next to **App Settings**, set **Provisioning** to **SCIM**, and save. A **Provisioning** tab appears.

**3. Connect Okta to Searchable**

On **Provisioning → Integration**, click **Edit** next to **SCIM Connection** and set:

| Setting | Value |
| - | - |
| SCIM connector base URL | The endpoint URL from step 1 |
| Unique identifier field for users | `userName` |
| Supported provisioning actions | **Push New Users**, **Push Profile Updates** and **Push Groups**. Leave the two Import options unticked. |
| Authentication Mode | **HTTP Header** |
| Authorization: Bearer | The SCIM token from step 1 |

Click **Test Connector Configuration**. It should pass. Then save.

**4. Choose what Okta sends**

On **Provisioning → To App**, click **Edit** next to **Provisioning to App**, enable **Create Users**, **Update User Attributes** and **Deactivate Users**, then save.

**5. Assign people**

On the app's **Assignments** tab, assign the people (or Okta groups of people) who should be in your Searchable workspace. Each one is added within a few seconds.

**6. Push groups (optional, for roles)**

If you want Okta groups to set roles, open the **Push Groups** tab, choose **Push Groups → Find groups by name**, find each group and push it. Then tell us which group should give which role (Admin, Member or Viewer) and we'll map them. See [Roles from Okta groups](#roles-from-okta-groups).

## What happens in Searchable

| In Okta | In Searchable |
| - | - |
| Assign someone to the SCIM app | Someone new joins with your SSO connection's default role. An existing member keeps the role they have, and someone your workspace invited gets the invitation's role. Once groups are mapped, their groups decide it. New accounts start unverified, with no password; their first SSO sign-in completes them. |
| Change someone's name | Updated, if their email is on one of your verified domains. Otherwise it's ignored. |
| Change someone's email | Not applied yet. Searchable keeps the email it already has. |
| Unassign someone from the SCIM app | Removed from your workspace. Their Searchable account isn't banned, and any other workspaces they belong to are untouched. |
| Deactivate someone in Okta | Okta unassigns them from every app, so they're removed as above. |
| Reassign or reactivate them | Someone on your verified domains is added back, with the default role or their groups' role. Someone on another domain comes back only if your workspace invites them again, with the invitation's role. Either can be refused if your workspace is at its seat limit. |
| Delete someone in Okta | Nothing more reaches Searchable. Okta only offers Delete for a person who's already deactivated, and by then they've been removed. |

> [!NOTE]
>
> **Okta never sends a delete.** Unassigning and deactivating both reach Searchable as "this person is
> no longer active", and Searchable removes them from your workspace. Their Searchable account stays,
> so reassigning someone on your verified domains brings them back (someone on another domain needs a
> new invitation first).

Searchable doesn't send people Okta adds an invitation. Let them know yourself that they can sign in with SSO.

### Who can be added

* **People on your verified domains** are added, whether or not they already have a Searchable account.
* **People on other domains** (a contractor's own address, say) are added only if your workspace invited them first or they're already a member. Anyone else is refused.
* **The workspace owner** can't be removed through SCIM. Transfer ownership first.
* **A super admin whose email is on another domain** can't be removed through SCIM either, so Okta can't remove someone your company doesn't own. Change their role in Searchable first. A super admin on your verified domains is removed like anyone else; if they're added back later, they return with the default role or their groups' role.

## Roles from Okta groups

Pushing groups doesn't change anyone's role on its own. Roles start following Okta only once we map at least one pushed group to a role. Before anything is saved, we see a preview of exactly who will change.

Once a group is mapped:

* Each person gets the **highest** role among their mapped groups (Admin, then Member, then Viewer).
* People on your verified domains who aren't in any mapped group get your SSO connection's **default role**.
* People on other domains who aren't in any mapped group keep their current role, even if a mapped group gave it to them. So removing a contractor from an Admin group leaves them an Admin: change their role in Searchable, or unassign them.
* The **owner** and **super admins** are never changed.
* Adding someone to a mapped group in Okta changes their role in Searchable as soon as Okta pushes the group, usually within a minute. A person must be assigned to the SCIM app first: Searchable skips group members that Okta hasn't pushed as people.

### "Managed by your identity provider"

When Okta decides someone's role, their role is locked in Searchable. In **Settings → Team**, their role control is disabled and shows **Managed by your identity provider**, and nobody in your workspace can change it there. Change their Okta groups instead.

Project access isn't locked. You can still choose which projects each person can reach.

To manage roles in Searchable again, ask us to unmap your groups. Everyone keeps the role they have at that moment, and the locks lift.

## Verify your setup

> [!TIP]
>
> **Test Connector Configuration** passes in Okta

> [!TIP]
>
> A test person you assign appears in **Settings → Team** with the expected role

> [!TIP]
>
> Unassigning that person removes them from **Settings → Team**

> [!TIP]
>
> If you use groups: after mapping, adding the test person to a mapped group changes their role, and it shows **Managed by your identity provider**

## Troubleshooting

> [accordion] Test Connector Configuration fails
>
> Check that the base URL is exactly the endpoint URL we sent and the authentication mode is **HTTP Header**. If the token was revoked, or SSO was turned off at any point (turning SSO off revokes every SCIM token, and turning it back on doesn't bring them back), ask us for a new token and paste it into Okta.

> [accordion] People are showing up in the wrong workspace
>
> The token decides the workspace. If your company has more than one Searchable workspace, check that the token in Okta is the one we issued for this workspace's SSO connection.

> [accordion] Someone was assigned but didn't appear
>
> Searchable refuses the push, and nothing is created, when:
>
> * their email isn't on one of your verified domains and your workspace hasn't invited them;
> * they already have a Searchable account with a password (or Google sign-in) that was never verified. Your owner and admins get an email about it, at most once a day. Ask the person to sign in once with SSO, then retry the push in Okta;
> * your workspace is at its seat limit. Your owner and admins get an email, at most once a day.
>
> We can see the reason for every refused request in your workspace's SCIM log. Contact [support@searchable.com](mailto:support@searchable.com) if you're not sure which applies.

> [accordion] I can't find a group in Push Groups
>
> Okta's group search matches the start of the group name. Type the first letters of the name, not a word from the middle.

> [accordion] Someone is in a mapped group but their role didn't change
>
> Check that they're assigned to the SCIM app as well as in the group: Searchable skips group members that Okta hasn't pushed as people. Also check they aren't the workspace owner or a super admin, whose roles never change.

> [accordion] I can't change someone's role in Searchable
>
> Their role is managed by Okta (see ["Managed by your identity provider"](#managed-by-your-identity-provider)). Change their groups in Okta, or ask us to unmap your groups so admins can manage roles in Searchable again.

> [accordion] Okta can't remove the workspace owner or a super admin
>
> Searchable refuses to remove the owner through SCIM: transfer ownership to someone else in Searchable first. It also refuses to remove a super admin whose email is on another domain: change their role in Searchable first, then unassign them in Okta again.

> [accordion] Okta is getting rate-limited
>
> Searchable accepts up to 600 SCIM requests a minute per SSO connection. Requests over that get a `429` response with a `Retry-After` header.

## Related

> [card] [Teams & Collaboration](https://docs.searchable.com/advanced/teams-collaboration.md)
>
> Roles, permissions and SSO sign-in


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.