> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/system-setup-and-configuration/users-access/scim.md).

# SCIM provisioning

Let your identity provider create, update and deactivate Sumble users automatically.

With SCIM, your identity provider (Okta or Rippling) manages Sumble accounts for you. Assign someone to the Sumble app in the IdP and they get a Sumble account with a seat. Unassign them, or deactivate them in the IdP, and they lose access to Sumble the same minute, including any API keys and MCP connections they set up.

SCIM requires [Okta SSO](https://docs.sumble.com/system-setup-and-configuration/users-access/okta-sso-oidc.md). Require Okta has to be on before Sumble issues a SCIM token, because deactivating someone in the IdP only locks them out if the IdP is the only way in.

***

### What Sumble supports

* SCIM 2.0, Users resource only. No groups.
* Create, read, update (PUT and PATCH), deactivate (`active: false`) and delete.
* Filtering by `userName` and `externalId`, which is what the IdP uses to match people on its first import.

Google Workspace can't call a custom SCIM endpoint, so it is not supported.

***

### Step 1: Get a token from Sumble

Ask your Sumble contact to turn on SCIM provisioning. They will send you two values:

* The **SCIM connector base URL**: `https://sumble.com/api/scim/v2`
* A **bearer token**. It is shown once. If it is lost, your Sumble contact can rotate it, and the old one stops working.

***

### Step 2: Okta

1. In Okta Admin Console, go to **Applications** > **Create App Integration** and select **SAML 2.0**. Create a separate app in the same Okta org, named e.g. "Sumble SCIM". People still sign in through the OIDC app from [Okta SSO](https://docs.sumble.com/system-setup-and-configuration/users-access/okta-sso-oidc.md). This app only provisions accounts, so its SAML sign-in settings are never used. Use these placeholder values:
   * **Single sign-on URL**: `https://sumble.com/`
   * **Audience URI**: `sumble-scim`
   * **Application username**: Email
2. Open **General** > **App Settings** > **Edit** and set **Provisioning** to **SCIM**. Save.
3. On the new **Provisioning** tab, under **Integration**, set:

   * **SCIM connector base URL**: the base URL from step 1
   * **Unique identifier field for users**: `userName`
   * **Supported provisioning actions**: Push New Users, Push Profile Updates, Push User Deactivation, Import New Users and Profile Updates
   * **Authentication Mode**: HTTP Header
   * **Authorization**: the bearer token from step 1

   Paste the token on its own, without a `Bearer` prefix.
4. Click **Test Connector Configuration**. Okta reads Sumble's SCIM metadata and reports what it supports.
5. Save, then open **Provisioning** > **To App** and enable **Create Users**, **Update User Attributes** and **Deactivate Users**.
6. Optional: run **Import** once. Okta lists everyone who already has a Sumble account at your domains and links them to their Okta users, so nothing is created twice.
7. Assign people or groups to both the SCIM app and the OIDC SSO app. The SCIM app provisions their accounts, and the OIDC app lets them sign in.

#### Attribute mapping

Sumble reads these attributes. Everything else Okta sends is ignored.

| Okta attribute            | Sumble                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `userName`                | Email address. Has to be at one of your Sumble domains. Can't be changed through SCIM. |
| `givenName`, `familyName` | Name                                                                                   |
| `displayName`             | Name, when the given and family names are not mapped                                   |
| `externalId`              | Okta's id for the user, used for matching                                              |
| `active`                  | Whether the person can sign in                                                         |

***

### Step 2: Rippling

1. In Rippling, open the Sumble app and start the **Custom SCIM** setup.
2. Enter the base URL and bearer token from step 1.
3. Map `userName` to the work email, and `givenName` and `familyName` to the name.
4. Turn on create, update and deactivate.

***

### What happens in Sumble

**A new user** gets a Sumble account on a Basic plan. If your seat subscription has a premium seat free, they take it straight away and start on Premium. If every licensed seat is taken, the account is created on Basic and a Sumble admin can assign a seat later from My Team. The IdP is never told no, so it does not keep retrying.

**Updates** to the name or `externalId` are applied as sent.

**Deactivating** someone, whether by unassigning them from the app, setting `active` to false, or deleting the user in the IdP, does the same thing as deactivating them from My Team:

* They can't sign in.
* Their open sessions end on their next request.
* Their API keys and MCP tokens stop working.
* Their seat is freed for someone else.
* Any open invitation for them is cancelled.

Their data stays. **Reactivating** them in the IdP lets them sign in again on Basic; a Sumble admin assigns a seat if they need one.

Sumble never hard-deletes an account through SCIM. To erase someone's data, contact Sumble.
