Set up Directory Sync (SCIM)

Let your identity provider add and remove members of your Enterprise workspace automatically.

Directory Sync lets your identity provider (IdP) manage who is in your Higgsfield workspace. When you assign someone to the Higgsfield app in your IdP, they're added to the workspace without an invitation. When you unassign or deactivate them, they're removed.

Directory Sync uses the SCIM 2.0 standard. It works with Okta, Microsoft Entra ID and other identity providers that support SCIM 2.0 provisioning.

Before you start

You'll need:

  • The Enterprise plan, in your main workspace. Directory Sync isn't available in sub-workspaces.
  • SSO set up for your company domains. Directory Sync appears in the Security section once your SSO connection exists, that is, after you select Continue in the SSO setup window. Finish SSO setup before you turn it on. See Set up SSO (SAML).
  • Owner access. Only the workspace Owner can turn Directory Sync on or off.
  • Admin access to your identity provider. Use the same app you created there for SSO.
  • An email address for every person you'll provision. People without an email in your IdP can't be added.

How Directory Sync works

How Directory Sync works

In your identity provider

In Higgsfield

You assign a person to the Higgsfield app

They're added to the workspace as a Member. No invitation needed.

You unassign or deactivate them

They're removed from the workspace.

You assign or reactivate them again

They're added back as a Member. Their previous role and group aren't restored.

A few rules to know:

  • Your IdP manages the people it adds. Members added by Directory Sync can't be removed in Higgsfield, and they can't leave the workspace themselves. Higgsfield shows This membership is managed by your identity provider and can only be ended there. Unassign or deactivate them in your IdP instead.
  • Invited members stay listed until you remove them. This covers everyone who joined by accepting an invitation, including everyone who was in the workspace before you turned on Directory Sync. If you deactivate one of them in your IdP, they can no longer sign in with SSO, but they stay in Members. Remove them in Manage account → Members.
  • Roles and groups stay in Higgsfield. Directory Sync adds and removes people. It doesn't sync groups or roles from your IdP. New people join as Members, and you can change their role or group in Manage account → Members. If someone has a pending invitation when Directory Sync adds them, they get the role and group from that invitation.
  • The workspace Owner stays in the workspace. Directory Sync never removes the Owner. Keep the Owner assigned and active in your IdP, though: if you deactivate them there, they can't sign in with SSO.

Step 1. Turn on Directory Sync

  1. Open Manage account → Organization.
  2. In the Security section, find Directory Sync (SCIM) and select Turn on.
  3. In the Connect your identity provider window, copy the SCIM URL and the Token.
    • The token is shown only once, so save both values somewhere safe before you continue. Treat the token like a password.
  4. Select Done.

Step 2. Connect your identity provider

Follow the steps for your provider.

Okta

Use the app integration you created for SSO.

  1. In the Okta Admin Console, go to Applications and Resources → Applications (Applications → Applications in older consoles) and open your Higgsfield app.
  2. On the General tab, select Edit in App Settings, set Provisioning to SCIM, and select Save. If there's no SCIM option, contact Okta Support to check whether provisioning can be turned on for your Okta organization.
  3. Open the Provisioning tab. Under Settings → Integration, select Edit and enter:
    • SCIM connector base URL: The SCIM URL from Higgsfield
    • Unique identifier field for users: userName
    • Supported provisioning actions: Push New Users and Push Profile Updates
    • Authentication Mode: HTTP Header. Paste the Token into the Authorization field
    • Test the connection, then select Save.
  4. Under Settings → To App, select Edit, turn on Create Users, Update User Attributes and Deactivate Users, and select Save.
  5. In the attribute mappings on the same page, check that email is mapped to user.email. Higgsfield needs it even when the username is already an email address.
  6. On the Assignments tab, send the people you already assigned for SSO: Okta doesn't send them on its own and marks them with a warning symbol. Select Provision Users. Then assign anyone else who should be in your Higgsfield workspace; Okta sends new assignments right away.

You don't need Push Groups: Higgsfield doesn't use groups from your IdP.

Microsoft Entra ID

Use the enterprise application you created for SSO.

  1. In the Microsoft Entra admin center, go to Entra ID → Enterprise apps → All applications (Enterprise applications in the Azure portal) and open your Higgsfield app.
  2. Select Provisioning, then New configuration. If your portal shows Provisioning Mode instead, set it to Automatic: the fields below are under Admin Credentials, and you turn provisioning on with Provisioning Status: On.
  3. Enter:
    • Tenant URL: the SCIM URL from Higgsfield.
    • Secret Token: the Token from Higgsfield.
  4. Select Test Connection. When it succeeds, select Create.
  5. Keep the scope set to Sync only assigned users and groups. Entra ID provisions the people and groups assigned under Users and groups, the same ones you assigned for SSO.
  6. Open Attribute mapping and check that the user mapping includes userName, emails[type eq "work"].value, name.givenName, name.familyName and active. They're usually there by default. Entra ID fills emails[type eq "work"].value from each user's mail attribute. If some people have no mailbox, set that mapping's source to userPrincipalName only if it matches the work email they use to sign in to Higgsfield. Otherwise, use an attribute that contains that email address.
  7. Select Start provisioning.

Entra ID syncs on a schedule, about every 40 minutes. The first sync takes longer. New people and removals don't appear in Higgsfield instantly. To send someone right away, use Provision on-demand.

Other identity providers

In your identity provider's SCIM 2.0 provisioning settings:

  • Use the SCIM URL as the SCIM base URL.
  • Use the Token as a Bearer token: Authorization: Bearer <token>.
  • Use userName as the unique identifier.
  • Send each person's work email in the SCIM emails attribute. An email in userName alone isn't enough.
  • Turn on creating, updating and deactivating users.

Step 3. Check that it works

Use a test account on your company domain that isn't already in the workspace, has no pending invitation and isn't the Owner.

  1. In your IdP, assign the test account to the Higgsfield app.
  2. In Higgsfield, open Manage account → Members. The test account appears as a Member. With Entra ID, use Provision on-demand or wait for the next sync.
  3. Unassign the test account in your IdP. It's removed from Members.

Once Directory Sync is on, the Security section shows Directory Sync (SCIM) with your provider's name (Okta or Microsoft Entra, or SCIM 2.0 if your SSO uses Google Workspace) and Your identity provider adds and removes members automatically.

Replace the token

Replace the token if it's lost or exposed:

  1. In the Security section, next to Directory Sync (SCIM), select New token.
  2. Select Generate token to confirm.
  3. Copy the new token and paste it into your IdP right away.

The previous token keeps working only for a short time. After that, your IdP can't sync members until it has the new token.

Turn off Directory Sync

  1. In the Security section, next to Directory Sync (SCIM), select Turn off.
  2. Select Turn off to confirm.

Your IdP stops adding and removing members, and the token stops working. Everyone already in the workspace stays, and you manage them in Manage account → Members as usual. Before you turn it off, remove anyone who shouldn't keep access. Turn off provisioning in your IdP too.

To turn Directory Sync on again later, select Turn on, replace both the SCIM URL and the Token in your IdP, and turn provisioning back on there.

Troubleshooting

Troubleshooting

What you see

What to do

Directory Sync (SCIM) isn't in the Security section

Check that you're the Owner of your main Enterprise workspace and that SSO is set up.

This membership is managed by your identity provider and can only be ended there.

Unassign or deactivate the person in your IdP.

A person is assigned in your IdP but isn't in Members

Check your IdP’s provisioning logs and confirm it sends the person’s work email in the SCIM emails attribute. In Entra ID, check the source you mapped to the work email field, such as mail. Wait for the next Entra ID sync or use Provision on-demand.

A person you deactivated is still in Members

Check the provisioning logs to confirm your IdP has sent the deactivation. Members who joined by invitation stay listed after deactivation. If they should no longer have workspace access, remove them in Manage account → Members.

Your IdP reports authentication errors

If Directory Sync is off, select Turn on and replace both the SCIM URL and the Token in your IdP. If it's on, the token was probably replaced: select New token and update your IdP.

Directory Sync is paused…

Contact enterprise@higgsfield.ai.

FAQ

Got any questions left?