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

# SCIM Provisioning

> Automate user provisioning and deprovisioning with SCIM 2.0

BuildBetter supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user lifecycle management. SCIM enables your identity provider to automatically create, update, and deactivate user accounts in BuildBetter.

<Info>
  SCIM provisioning is available for Enterprise customers with custom SAML SSO integrations. Contact your account representative to enable SCIM for your organization.
</Info>

## Overview

SCIM automates the user provisioning process, ensuring that:

* **New employees** automatically get BuildBetter access when added to your identity provider
* **Departing employees** are immediately deprovisioned when removed from your identity provider
* **User profile changes** (name, email) are synced automatically
* **Account management** is centralized in your identity provider

<CardGroup cols={2}>
  <Card title="Automatic Provisioning" icon="user-plus">
    New users are created in BuildBetter when assigned in your IdP
  </Card>

  <Card title="Automatic Deprovisioning" icon="user-minus">
    Users are deactivated when unassigned or removed from your IdP
  </Card>

  <Card title="Profile Sync" icon="arrows-rotate">
    User profile updates are synchronized automatically
  </Card>

  <Card title="Centralized Control" icon="shield-check">
    Manage all access from your identity provider
  </Card>
</CardGroup>

## Supported Identity Providers

BuildBetter's SCIM implementation works with any SCIM 2.0 compliant identity provider, including:

* **Okta**
* **Azure Active Directory (Entra ID)**
* **OneLogin**
* **JumpCloud**
* **Google Workspace** (with SCIM connector)
* **Ping Identity**

## SCIM Capabilities

### Supported Operations

| Operation       | Description                          | Supported |
| --------------- | ------------------------------------ | --------- |
| Create User     | Provision new users in BuildBetter   | Yes       |
| Update User     | Modify user profile attributes       | Yes       |
| Deactivate User | Disable user access without deletion | Yes       |
| Delete User     | Remove user from BuildBetter         | Yes       |
| Get User        | Retrieve user information            | Yes       |
| List Users      | Retrieve all provisioned users       | Yes       |

### Supported Attributes

BuildBetter supports the following SCIM user attributes:

| SCIM Attribute    | BuildBetter Field                  | Required |
| ----------------- | ---------------------------------- | -------- |
| `userName`        | Email address (primary identifier) | Yes      |
| `name.givenName`  | First name                         | Yes      |
| `name.familyName` | Last name                          | Yes      |
| `active`          | Account status                     | Yes      |
| `emails[primary]` | Primary email                      | Yes      |
| `displayName`     | Display name                       | No       |

<Note>
  Role-based access control (RBAC) and department assignments are managed within BuildBetter's admin settings rather than through SCIM. This allows for flexible permission configurations that may not map directly to your IdP's group structure.
</Note>

## Setting Up SCIM with Okta

Follow these steps to configure SCIM provisioning with Okta:

<Steps>
  <Step title="Request SCIM Configuration">
    Contact BuildBetter support at [support@buildbetter.ai](mailto:support@buildbetter.ai) to request SCIM provisioning setup. We'll provide you with:

    * SCIM Base URL
    * API Bearer Token for authentication
    * Any organization-specific configuration details
  </Step>

  <Step title="Create SCIM Application in Okta">
    1. Log in to your Okta Admin Console
    2. Navigate to **Applications** > **Applications**
    3. Click **Create App Integration**
    4. Select **SAML 2.0** (if you haven't already configured SAML SSO)
    5. Or select your existing BuildBetter SAML application
  </Step>

  <Step title="Configure Provisioning">
    1. In your BuildBetter application, go to the **Provisioning** tab
    2. Click **Configure API Integration**
    3. Check **Enable API Integration**
    4. Enter the SCIM Base URL provided by BuildBetter:
       ```
       https://api.buildbetter.ai/scim/v2
       ```
    5. Enter the API Token (Bearer Token) provided by BuildBetter
    6. Click **Test API Credentials** to verify the connection
    7. Click **Save**
  </Step>

  <Step title="Enable Provisioning Features">
    After saving the API configuration:

    1. Go to **Provisioning** > **To App**
    2. Click **Edit**
    3. Enable the following options:
       * **Create Users** - Provision new users
       * **Update User Attributes** - Sync profile changes
       * **Deactivate Users** - Disable access when unassigned
    4. Click **Save**
  </Step>

  <Step title="Configure Attribute Mappings">
    1. Go to **Provisioning** > **To App** > **Attribute Mappings**
    2. Verify the following mappings are configured:

    | Okta Attribute   | BuildBetter Attribute   |
    | ---------------- | ----------------------- |
    | `user.email`     | `userName`              |
    | `user.firstName` | `name.givenName`        |
    | `user.lastName`  | `name.familyName`       |
    | `user.email`     | `emails[primary].value` |

    3. Click **Save** after making any changes
  </Step>

  <Step title="Assign Users">
    1. Go to the **Assignments** tab
    2. Click **Assign** > **Assign to People** or **Assign to Groups**
    3. Select the users or groups that should have access to BuildBetter
    4. Click **Save and Go Back**
    5. Click **Done**

    Assigned users will be automatically provisioned in BuildBetter.
  </Step>
</Steps>

<Warning>
  Keep your SCIM API token secure. If you believe your token has been compromised, contact BuildBetter support immediately to rotate the credentials.
</Warning>

## Setting Up SCIM with Azure AD (Entra ID)

<Steps>
  <Step title="Request SCIM Configuration">
    Contact [support@buildbetter.ai](mailto:support@buildbetter.ai) to receive your SCIM credentials.
  </Step>

  <Step title="Configure Enterprise Application">
    1. Log in to the Azure Portal
    2. Navigate to **Azure Active Directory** > **Enterprise Applications**
    3. Select your existing BuildBetter application or create a new one
    4. Go to **Provisioning** in the left menu
    5. Set **Provisioning Mode** to **Automatic**
  </Step>

  <Step title="Enter Admin Credentials">
    In the **Admin Credentials** section:

    * **Tenant URL**: Enter the SCIM Base URL from BuildBetter
      ```
      https://api.buildbetter.ai/scim/v2
      ```
    * **Secret Token**: Enter the API Bearer Token from BuildBetter

    Click **Test Connection** to verify, then **Save**
  </Step>

  <Step title="Configure Mappings">
    1. Expand **Mappings**
    2. Select **Provision Azure Active Directory Users**
    3. Verify the attribute mappings match your requirements
    4. Enable the mapping and save
  </Step>

  <Step title="Start Provisioning">
    1. Set **Provisioning Status** to **On**
    2. Click **Save**
    3. Azure AD will begin initial synchronization
  </Step>
</Steps>

## User Lifecycle Management

### When a User is Assigned

When you assign a user to BuildBetter in your identity provider:

1. The IdP sends a SCIM create request to BuildBetter
2. BuildBetter creates the user account with the provided attributes
3. The user receives a welcome email (if enabled)
4. The user can sign in via SSO immediately

### When a User is Updated

When you update a user's profile in your identity provider:

1. The IdP sends a SCIM patch request to BuildBetter
2. BuildBetter updates the user's profile with the new attributes
3. Changes take effect immediately

### When a User is Unassigned or Deactivated

When you remove a user's access in your identity provider:

1. The IdP sends a SCIM deactivate request to BuildBetter
2. BuildBetter deactivates the user account
3. The user can no longer sign in
4. User's data is retained according to your data retention policy

<Info>
  Deactivated users' data remains accessible to administrators for compliance and audit purposes. If you need to permanently delete user data, contact [support@buildbetter.ai](mailto:support@buildbetter.ai).
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Users not being provisioned" icon="user-xmark">
    **Common causes:**

    * API credentials are incorrect or expired
    * User is not assigned to the application in your IdP
    * Required attributes (email, first name, last name) are missing

    **Solutions:**

    1. Test the API connection in your IdP's provisioning settings
    2. Verify the user is assigned to the BuildBetter application
    3. Check that all required user attributes are populated
    4. Review provisioning logs in your IdP for specific error messages
  </Accordion>

  <Accordion title="Profile changes not syncing" icon="arrows-rotate">
    **Common causes:**

    * Attribute mappings are misconfigured
    * Provisioning is paused or disabled
    * Rate limiting on API requests

    **Solutions:**

    1. Verify attribute mappings in your IdP
    2. Ensure provisioning is enabled and running
    3. Trigger a manual sync if available
    4. Wait a few minutes and check again (some IdPs batch updates)
  </Accordion>

  <Accordion title="Users not being deprovisioned" icon="user-slash">
    **Common causes:**

    * Deactivation is not enabled in provisioning settings
    * User was removed from IdP but not unassigned from the app

    **Solutions:**

    1. Verify "Deactivate Users" is enabled in provisioning settings
    2. Ensure the user was properly unassigned from the application
    3. Check provisioning logs for any errors
    4. Contact BuildBetter support if the issue persists
  </Accordion>

  <Accordion title="API connection test failing" icon="plug-circle-xmark">
    **Common causes:**

    * Incorrect SCIM Base URL
    * Invalid or expired API token
    * Network/firewall blocking the connection

    **Solutions:**

    1. Verify the SCIM Base URL is exactly: `https://api.buildbetter.ai/scim/v2`
    2. Request a new API token from BuildBetter support
    3. Ensure your network allows outbound HTTPS connections to BuildBetter
  </Accordion>
</AccordionGroup>

## Security Considerations

### Authentication

* SCIM requests are authenticated using Bearer tokens
* Tokens are organization-specific and can be rotated on request
* All SCIM traffic is encrypted via TLS 1.2+

### Audit Logging

All SCIM operations are logged for compliance purposes:

* User creation events
* Profile updates
* Deactivation events
* API authentication attempts

Enterprise customers can access these logs through the audit log feature.

### Data Protection

* SCIM data is transmitted over encrypted connections only
* User data is stored according to BuildBetter's data security policies
* Deactivated users can be permanently deleted upon request

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I use SCIM without SSO?" icon="key">
    SCIM provisioning is typically paired with SAML SSO for a complete identity management solution. Contact your account representative to discuss your specific requirements.
  </Accordion>

  <Accordion title="Are groups/roles supported via SCIM?" icon="users">
    Currently, BuildBetter manages roles and permissions within the application rather than through SCIM group provisioning. This provides flexibility for complex permission structures that may not map directly to your IdP's group hierarchy.
  </Accordion>

  <Accordion title="How quickly are changes synced?" icon="clock">
    Most identity providers sync changes within minutes. The exact timing depends on your IdP's provisioning schedule and configuration.
  </Accordion>

  <Accordion title="Can I provision users to multiple workspaces?" icon="building">
    Yes. Contact BuildBetter support to configure multi-workspace provisioning based on your organizational structure.
  </Accordion>

  <Accordion title="What happens to existing users when I enable SCIM?" icon="circle-question">
    Existing users can be linked to your IdP through email matching. Contact BuildBetter support to coordinate the initial sync and avoid duplicate accounts.
  </Accordion>
</AccordionGroup>

***

<Note>
  For assistance with SCIM configuration or to request SCIM provisioning for your organization, contact [support@buildbetter.ai](mailto:support@buildbetter.ai) or your account representative.
</Note>