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

# Provision people and teams with SCIM

> Connect Microsoft Entra ID, Okta, or another SCIM 2.0 directory so employees are ready before their first OpenWhispr sign-in.

SCIM lets your identity provider create and deactivate OpenWhispr workspace members and keep group membership in sync. After setup, an assigned employee signs in with company SSO and their workspace, teams, and managed AI settings are already available.

## Before you start

You need:

* an active OpenWhispr Enterprise workspace with owner or admin access
* a verified company domain connected to SAML or OIDC under **Security > Single sign-on**
* administrator access to your identity provider
* enough workspace seats for the people you assign

<Note>
  Keep **Allow just-in-time fallback** on during your pilot. Existing employees can continue to join through verified company SSO even if they have not been pushed through SCIM yet.
</Note>

## Connect your directory

<Steps>
  <Step title="Enable directory sync">
    In the OpenWhispr admin portal, open **Security > Directory sync**, explicitly select the verified SSO provider for this directory, and select **Enable directory sync**. Pause directory sync before moving the connection to another verified provider.
  </Step>

  <Step title="Create a provisioning token">
    Select **Create token**, then copy both the **SCIM base URL** and token. The full token is shown once and expires after 90 days by default. Store it in your identity provider, not in a shared document or ticket.
  </Step>

  <Step title="Configure your identity provider">
    Use the SCIM base URL as the tenant or connector URL and the token as a bearer token. Then configure the attributes and actions below.

    <Tabs>
      <Tab title="Microsoft Entra ID">
        In the enterprise application you use for OpenWhispr, open **Provisioning**, choose automatic provisioning, and enter the OpenWhispr tenant URL and secret token.

        Use **Sync only assigned users and groups** for a controlled rollout. Test the connection, assign a pilot group, then start provisioning.
      </Tab>

      <Tab title="Okta">
        In the OpenWhispr application, enable SCIM provisioning and enter the OpenWhispr base URL and bearer token.

        Enable **Create users**, **Update user attributes**, **Deactivate users**, and **Push groups**. Assign a pilot group before expanding the rollout.
      </Tab>

      <Tab title="Another SCIM provider">
        Configure a SCIM 2.0 bearer-token connector. OpenWhispr supports Users, Groups, PATCH, filtering, pagination, and ETags. Bulk requests, password changes, and sorting are not supported.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Map user attributes">
    Send these standard SCIM attributes:

    | OpenWhispr field    | SCIM attribute                        | Requirement                     |
    | ------------------- | ------------------------------------- | ------------------------------- |
    | Work email          | `userName` and primary `emails.value` | Required; must be a valid email |
    | Directory object ID | `externalId`                          | Recommended                     |
    | Status              | `active`                              | Required for deprovisioning     |
    | Full name           | `displayName`                         | Recommended                     |
    | Name parts          | `name.givenName`, `name.familyName`   | Optional                        |

    Group pushes use `displayName`, `externalId`, and `members[].value`.
  </Step>

  <Step title="Verify the pilot">
    Return to **Security > Directory sync**. Confirm that the assigned people and groups appear, then have a pilot employee choose company SSO in the desktop app.

    Their first SSO session links the pre-provisioned directory record to their OpenWhispr identity. No invitation, API key, AWS profile, or Azure key is required.
  </Step>

  <Step title="Enforce the final state">
    After every intended employee is visible in the directory table, turn off **Allow just-in-time fallback**. Then enable **Require SSO** under **Security > Single sign-on**.

    Turning off the fallback removes every non-owner workspace member who does not have an active linked directory record, including their workspace-team memberships. The confirmation shows the exact number first. Verify the directory table before continuing.

    From that point, only active people assigned by your directory can enter the workspace, and password or social sign-in cannot be used for the verified domain.

    Enabling it also ends sessions that did not come through your IdP, so an admin who signed in with a password is returned to sign-in to re-authenticate. The workspace owner keeps admin-console access without an SSO session, so a misconfigured IdP can always be undone.
  </Step>
</Steps>

## What each directory change does

| Identity-provider change          | OpenWhispr result                                                                                                     |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Assign an active user             | Reserves a workspace seat and prepares the account before first login                                                 |
| Update a user's name or email     | Updates the directory record                                                                                          |
| Add a user to a pushed group      | Adds the linked employee to the matching team                                                                         |
| Remove a user from a pushed group | Removes them from that team                                                                                           |
| Deactivate or delete a user       | Removes workspace and team access at any role except owner; it does not delete the person's global OpenWhispr account |
| Push a group                      | Creates or updates a SCIM-managed team                                                                                |
| Delete a group                    | Archives the SCIM-managed team so its history is preserved                                                            |

SCIM-managed teams are read-only in the OpenWhispr admin portal. Change their names and membership in your identity provider so the two systems do not drift.

Directory changes take effect when the identity provider sends the next successful SCIM request. Scheduled sync timing and retries are controlled by that provider, so a change made in Entra or Okta may not appear immediately. For urgent offboarding, revoke the employee's IdP session, run an on-demand provisioning cycle, and verify that the person is inactive in the OpenWhispr directory table. Deactivation removes cloud workspace and team access when OpenWhispr receives it; it does not remotely erase notes already stored on an employee device.

## Supported SCIM operations

The connection exposes `/Users`, `/Groups`, `/ServiceProviderConfig`, `/Schemas`, and `/ResourceTypes` below the base URL shown in the admin portal.

| Resource   | Supported operations                                                   |
| ---------- | ---------------------------------------------------------------------- |
| Users      | List, create, get, replace, patch, and deactivate                      |
| Groups     | List, create, get, replace, patch, and delete                          |
| Filters    | Single `eq` lookup by ID, external ID, username, or group display name |
| Pagination | `startIndex` and `count`, up to 200 results per page                   |

Requests are limited to 600 per minute per directory connection. A `429` response includes `Retry-After`.

## Rotate or revoke a token

Select **Rotate token** to create a second active token. Update the identity provider, run a test sync, then revoke the old token. Keeping both active for the short cutover avoids an interruption.

Tokens expire after 90 days by default. Revocation is immediate, and an expired or revoked token cannot provision or deactivate anyone.

## Troubleshooting

| Symptom                                | What to check                                                                                                        |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Connection test returns `401`          | The bearer token is complete, has not been revoked, and belongs to this workspace                                    |
| Provisioning returns `409`             | The workspace has an available seat and the email or `externalId` is not already assigned to another record          |
| Employee is told they are not assigned | Their SCIM record is active, their SSO email matches `userName`, and just-in-time fallback is configured as intended |
| Group membership is missing            | Push the group after its users and confirm member references use the OpenWhispr SCIM user IDs                        |
| SSO works but managed AI does not      | The employee used company SSO for the current session and the managed provider is active                             |

## Related

* [Managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai)
* [Enterprise providers](/guides/enterprise)
* [Network allowlist](/help/it/network-allowlist)