Skip to main content

Setting Up SCIM Provisioning (Okta and Microsoft Entra ID)

How to connect Okta or Microsoft Entra ID to VeryBusy to automatically provision, update, and deactivate workspace members, assign workspace roles, and manage seats — for Enterprise workspace owners.

VeryBusy supports SCIM 2.0, so your identity provider (IdP) can automatically create, update, and deactivate VeryBusy accounts for your team, and assign each person the right workspace role.

SCIM Provisioning is an Enterprise-plan feature. If you're on Studio or Pro, contact enterprise@verybusy.io to move to Enterprise.

Supported identity providers: Okta and Microsoft Entra ID (formerly Azure AD).

Who can access SCIM Provisioning

  • Workspace owner (Enterprise): full access — enable/disable SCIM, generate and rotate the token, turn Auto-buy seats on/off, and view Sync History.

  • Other workspace members (Enterprise): see the Provisioning section locked, with the message "Request your workspace owner to contact VeryBusy to grant you access."

  • Studio or Pro (any role): the section is locked behind an upgrade prompt.

Need an IT admin (not the owner) to manage this? Have the workspace owner contact support@verybusy.io and we'll set it up.

How it works

  • Assigning a user to the VeryBusy app in your IdP creates their account (if needed) and adds them to your workspace with a seat. New users get a password-reset email.

  • The workspace role is taken from the roles attribute your IdP sends — Editor or Manager. See "Assigning workspace roles" below.

  • Already a member? If the person is already in your workspace (for example, you invited them before turning on SCIM), they're linked to your IdP instead of duplicated. Their current role is kept.

  • Updating a user's profile (name or email) in your IdP updates it in VeryBusy.

  • Deactivating or unassigning a user in your IdP immediately removes their access to the workspace and all its projects. They stay in your members list, marked inactive.

  • Reactivating a user in your IdP restores their access exactly as it was.

Members created or linked through SCIM show a SCIM badge in your workspace Members list.

Before you begin

  • You must be the workspace owner on an Enterprise workspace.

  • SCIM must be activated for your workspace by VeryBusy. If you're on Enterprise but can't generate a SCIM token from the Provisioning tab, contact support@verybusy.io and we'll activate it.

  • Check your seats. Every provisioned member uses a seat. Make sure you have enough free seats for everyone you'll assign, or turn on Auto-buy seats (see below).

  • Have your IdP admin credentials ready (Okta admin, or Entra ID Application Administrator).

Step 1 — Get your SCIM credentials in VeryBusy

  1. Go to Workspace Settings → Provisioning. On first visit, the status shows Not configured.

  2. Click Generate Token to create your SCIM token. It's shown exactly once — copy it immediately. After you leave the screen, it's masked permanently.

  3. Note your SCIM Base URL: https://api.verybusy.io/scim/v2

Keep the token safe. Anyone with it can manage your workspace members. If it's compromised, click Rotate to generate a new one, then update your IdP.

Step 2 — Decide how to handle seats (Auto-buy seats)

On the same Provisioning tab, the Auto-buy seats setting controls what happens when your IdP provisions someone and the workspace is full:

  • Off (default): the new user is added only if a seat is free. If not, provisioning fails and your IdP shows a member-limit error.

  • On: if no seat is free, VeryBusy buys one seat and assigns it to the new user. Choose the billing period (Annual or Monthly) for seats bought this way. A free, already-paid seat in either period is always used first, before anything is bought.

Step 3 — Connect your identity provider

The pattern is the same for every IdP: create an app for VeryBusy, paste the SCIM Base URL and token, test the connection, enable provisioning actions, map the roles attribute, then assign users or groups.

Configure Okta

  1. In the Okta Admin Console, go to Applications → Browse App Catalog, search for "SCIM 2.0 Test App (Header Auth)", and select Add Integration. Name it "VeryBusy".

  2. Complete the wizard with the defaults — sign-on settings aren't used for provisioning.

  3. Open Provisioning → Configure API Integration → check Enable API integration, then fill in:

    • SCIM 2.0 Base Url: https://api.verybusy.io/scim/v2

    • Unique identifier field for users: userName

    • Authorization (Bearer): your VeryBusy SCIM token

  4. Click Test API Credentials, then Save.

  5. In Provisioning → To App, click Edit and enable Create Users, Update User Attributes, and Deactivate Users.

  6. Map the role (optional but recommended): in Directory → Profile Editor, open the VeryBusy app profile and add an attribute with:

    • External name: roles

    • External namespace: urn:ietf:params:scim:schemas:core:2.0:User

    Then in Mappings, map it from the Okta user field that holds each person's VeryBusy role (Editor or Manager).

  7. Go to Assignments and assign the users or groups you want to provision.

⚠️ Okta suspend is not supported. Suspending a user in Okta doesn't notify VeryBusy. Use Deactivate or unassign the user instead.

Configure Microsoft Entra ID

  1. In the Microsoft Entra admin center, go to Entra ID → Enterprise apps → + New application → + Create your own application.

  2. Name it "VeryBusy", choose "Integrate any other application you don't find in the gallery (Non-gallery)", and select Add.

  3. Open Provisioning and create a new configuration (classic UI: Get started → Provisioning Mode: Automatic).

  4. Fill in:

    • Tenant URL: https://api.verybusy.io/scim/v2

    • Secret Token: your VeryBusy SCIM token

  5. Click Test Connection, then save.

  6. Map the role (optional but recommended): under Mappings → Provision Microsoft Entra ID Users, add a mapping to the target attribute roles[primary eq "True"].value, sourced from the field that holds each person's VeryBusy role (Editor or Manager).

  7. Under Users and groups, assign the users or groups to sync. Only direct members of an assigned group sync — nested groups aren't resolved.

  8. Click Start provisioning.

Good to know:

  • Entra syncs roughly every 40 minutes. To push one user immediately, use Provision on demand.

  • Disabling or deleting a user in Entra both deactivate the member in VeryBusy.

  • Provisioning errors appear under Enterprise apps → Provisioning logs in Entra.

Assigning workspace roles

VeryBusy sets each provisioned member's workspace role from the roles attribute your IdP sends (in Entra, mapped as roles[primary eq "True"].value):

What your IdP sends in roles

Role in VeryBusy

Manager

Manager

Editor

Editor

Nothing, empty, or any other value

Editor

Owner

Owner can't be assigned through SCIM

  • Nobody gets Manager by default. If you don't map roles, everyone joins as Editor.

  • The role is set when the person is first provisioned. To change it later, update it in VeryBusy from the Members list.

  • People who were already in the workspace before SCIM keep their existing role.

  • Project-level roles aren't set through SCIM — see what permissions each project role has.

Signing in after being provisioned

Provisioned members can sign in either way:

  • Set a password using the reset email they receive, or

  • Log in with Microsoft (or Google) using the same email. Their account is linked on first sign-in.

What you'll see in VeryBusy

Status

Meaning

Not configured

SCIM has never been enabled. No token exists yet.

Active

SCIM is on. Shows the Base URL, a masked token, and "Last sync": a timestamp, "Never synced yet", or a warning if the last sync had errors.

Disabled

The owner turned SCIM off. The token is kept but your IdP can't authenticate. Click "Re-enable SCIM" to resume.

From Active, the owner can Rotate the token (update your IdP before the old one stops working) or Revoke it (IdP loses access immediately).

Sync History

Sync History logs every provisioning event from your IdP: status icon, action, user email, and timestamp.

Icon

Action

What it means

✓

provisioned

A user was created and added, or an existing member was linked.

✓

updated

A user's name or email changed from the IdP.

✓

deactivated

A user was deactivated or unassigned and lost access.

✓

reactivated

A deactivated user was reactivated and regained access.

✕

provision_failed

Creating or linking the user failed — most often because the workspace has no free seats.

✕

update_failed

An update from the IdP couldn't be applied.

✕

deactivation_failed

A deactivation request couldn't be applied.

For the exact error behind a failure, check your IdP's logs (Okta: the app's Tasks / System Log; Entra: Provisioning logs).

Events load 20 at a time, most recent first.

Deactivation and removal — when someone leaves

When your IdP deactivates a user:

  • They immediately lose access to the workspace and all its projects.

  • They stay in your Members list, marked inactive, and still use a seat.

  • Their data stays intact — owned projects, comments, project memberships.

If they're reactivated, everything is restored.

If they're not coming back, remove them manually from Members. This frees the seat and transfers any projects they owned to the workspace owner (see project ownership transfer).

Why isn't removal automatic? IdP deactivations are sometimes temporary or accidental. Keeping the member inactive makes it fully reversible.

Limitations

  • Groups: you can assign groups to the VeryBusy app in your IdP to choose who syncs, but group push and group-to-role mapping aren't supported. Roles come from the per-user roles attribute.

  • Okta suspend: not supported — use Deactivate.

  • Passwords: not synced.

  • Owner role: can't be assigned through SCIM.

  • Project roles: not set through SCIM.

  • One token per workspace: generating a new token invalidates the previous one.

Troubleshooting

Issue

Resolution

I'm on Enterprise but can't generate a SCIM token

SCIM needs to be activated for your workspace. Contact support@verybusy.io.

"Test API Credentials" / "Test Connection" fails

Check the Base URL is exactly https://api.verybusy.io/scim/v2 and the token has no extra spaces. If you rotated the token, update it in the IdP.

Assignment fails: "Workspace has reached its member limit"

No free seats. Add seats in VeryBusy, turn on Auto-buy seats, or remove an inactive member — then retry the assignment in your IdP.

Everyone arrived as Editor

Your IdP isn't sending roles, or the value isn't Editor/Manager. Check the attribute mapping, then adjust existing members' roles in VeryBusy.

An existing member kept their old role

Expected — members who were already in the workspace are linked with their current role. Change it from Members.

Provisioned user can't log in with Microsoft

Make sure they use the same email as in your IdP. If it still fails, contact support.

Deactivated user still in the Members list

Expected — remove them manually to free the seat.

Suspended Okta user still has access

Okta doesn't notify VeryBusy on suspend. Deactivate or unassign instead.

Entra: changes take a long time

Entra syncs roughly every 40 minutes. Use "Provision on demand".

Still stuck? Reach out to support@verybusy.io and we'll help you get connected.

Related Articles
Did this answer your question?