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.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
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 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.
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:
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.
What happens in Searchable
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).
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
Test Connector Configuration passes in Okta
A test person you assign appears in Settings → Team with the expected role
Unassigning that person removes them from Settings → Team
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
Test Connector Configuration fails
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.
People are showing up in the wrong workspace
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.
Someone was assigned but didn't appear
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.
I can't find a group in Push Groups
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.
Someone is in a mapped group but their role didn't change
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.
I can't change someone's role in Searchable
I can't change someone's role in Searchable
Their role is managed by Okta (see “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.
Okta can't remove the workspace owner or a super admin
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.
Okta is getting rate-limited
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
Teams & Collaboration
Roles, permissions and SSO sign-in