# Set up SCIM provisioning

For IT admins: create, update and suspend DraftPilot accounts automatically from Microsoft Entra ID or Okta, and map directory departments to workspaces and personas.

SCIM provisioning keeps DraftPilot in step with your directory. Once it's on, your identity provider:

-   **creates** a DraftPilot account when you assign someone to the app,
-   **updates** their name and email when they change in your directory,
-   **suspends** their account when you unassign, disable or delete them, and reactivates it if you assign them again,
-   **gives them workspaces and a persona** based on their department, using the group access mappings you set up in DraftPilot.

This guide covers Microsoft Entra ID (formerly Azure AD) and Okta. DraftPilot implements the SCIM 2.0 Users API, so other SCIM 2.0 clients can connect with the same URL and token.

SCIM creates accounts but doesn't sign anyone in. Pair it with [SAML single sign-on](/knowledge-base/saml-and-okta-single-sign-on) so provisioned users can sign in with their work account.

## Before you start

You need:

-   **A DraftPilot admin account.** Only organization admins can open [Organization settings](https://app.draftpilot.ai/organization-settings?tab=scim).
-   **Admin access to your identity provider**, enough to configure provisioning on an enterprise application (Entra ID) or app integration (Okta).
-   **SCIM provisioning on your DraftPilot plan.** If the **SCIM provisioning** tab shows a **Contact us** button, SCIM isn't enabled for your organization yet. Click **Contact us**, or email [support@draftpilot.ai](mailto:support@draftpilot.ai), and we'll turn it on.

Things to know before you switch it on:

-   **Your directory takes over inviting.** As soon as your identity provider first connects, the invite buttons on DraftPilot's Users page are turned off and admins see *"User provisioning is managed via SCIM. Contact your IT team to invite users."* If you need to invite someone by hand later, ask [support@draftpilot.ai](mailto:support@draftpilot.ai).
-   **New users get a welcome email** from DraftPilot when their account is created.
-   **New users get your organization's default sign-in method.** For SSO organizations that's SAML single sign-on. If provisioned users are asked for a password, see [Troubleshooting](#provisioned-users-are-asked-for-a-password).
-   **Existing accounts are reused.** If someone already has a DraftPilot account with the same email, SCIM takes it over rather than creating a duplicate.

## DraftPilot values to copy

| Field | EU | US |
| --- | --- | --- |
| Tenant URL (SCIM connector base URL) | `https://api.draftpilot.ai/v1/scim` | `https://api-us.draftpilot.ai/v1/scim` |
| Secret token | Generated on the **SCIM provisioning** tab | Generated on the **SCIM provisioning** tab |

DraftPilot expects the token in an `Authorization: Bearer <token>` header. Entra ID and Okta add this for you.

Use the column for the region your organization's data is hosted in. If you're not sure, copy the **SCIM endpoint URL** from the **SCIM provisioning** tab, which always shows your region's URL. A token only works against its own region.

## Generate your SCIM token

1.  Sign in to DraftPilot in your browser and open [Organization settings > SCIM provisioning](https://app.draftpilot.ai/organization-settings?tab=scim).
2.  Under **Set up SCIM provisioning**, click **Generate SCIM token**.
3.  Copy the **SCIM endpoint URL** and the **SCIM token**.

Treat the token like a password. It lets anyone who holds it create and suspend accounts in your organization.

**Regenerate SCIM token** creates a new token and immediately invalidates the old one. Provisioning stops until you paste the new token into your identity provider, so only regenerate when you're ready to update it straight away, or if the token may have leaked.

## Set up Microsoft Entra ID provisioning

You can add provisioning to the DraftPilot enterprise application you created for [SAML single sign-on](/knowledge-base/saml-and-okta-single-sign-on), so the same assignments control both sign-in and provisioning. If you don't use SAML, create a new non-gallery application: in **Enterprise applications**, click **New application > Create your own application**, and choose **Integrate any other application you don't find in the gallery (Non-gallery)**.

### Connect to DraftPilot

1.  In the application, open **Provisioning** and click **New configuration** (or **Get started**).
2.  Set **Provisioning Mode** to **Automatic**.
3.  Under **Admin Credentials**, enter:
    -   **Tenant URL:** your DraftPilot SCIM endpoint URL
    -   **Secret Token:** your DraftPilot SCIM token
4.  Click **Test Connection**, then save.

### Check the attribute mappings

1.  Open **Mappings**.
2.  Open **Provision Microsoft Entra ID Groups**, set **Enabled** to **No**, and save. DraftPilot doesn't use SCIM groups (see [Give groups access](#give-groups-access-to-workspaces-and-personas)), so there's nothing to gain from pushing them.
3.  Open **Provision Microsoft Entra ID Users** and check these mappings. The defaults are usually right:

| DraftPilot (SCIM) attribute | Entra ID source | Notes |
| --- | --- | --- |
| `userName` | `userPrincipalName` | Change the source to `mail` if your users' UPNs differ from their email addresses. DraftPilot updates the account email from this attribute. |
| `emails[type eq "work"].value` | `mail` | Becomes the DraftPilot account email when the account is created. |
| `active` | `Switch([IsSoftDeleted], ...)` | Suspends and reactivates the account. Keep the default. |
| `displayName` | `displayName` | |
| `name.givenName` | `givenName` | |
| `name.familyName` | `surname` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department` | `department` | Drives workspace and persona mappings. |

DraftPilot ignores any other attributes Entra ID sends, such as job title, phone numbers and manager.

The account email must match the email your SAML sign-in sends, or the user won't be able to sign in. If UPN and email differ in your tenant, map `userName` from `mail`. Otherwise a later update can replace the DraftPilot email with the UPN, and email changes in your directory won't reach DraftPilot.

### Choose who is provisioned

1.  In **Provisioning > Settings**, set **Scope** to **Sync only assigned users and groups**.
2.  In **Users and groups**, assign the people or groups who should get DraftPilot. Assigning a group provisions its members. Entra ID doesn't provision members of nested groups.

### Test, then start

1.  Click **Provision on demand**, pick a test user, and click **Provision**. Entra ID shows each step, and any error DraftPilot returns.
2.  In DraftPilot, open the [Users page](https://app.draftpilot.ai/users) and check the user appears in the workspaces you expect.
3.  Back in **Provisioning**, set **Provisioning Status** to **On** and save.

Entra ID provisions everyone in scope in its first cycle, then syncs changes roughly every 40 minutes. Use **Provision on demand** when you need a change to go through straight away.

## Set up Okta provisioning

DraftPilot supports Okta's user provisioning: creating users, pushing profile updates, and deactivating and reactivating users. It doesn't support Okta's **Push Groups**. Use [department mappings](#give-groups-access-to-workspaces-and-personas) instead.

Add provisioning to the DraftPilot SAML app you created for [SAML single sign-on](/knowledge-base/saml-and-okta-single-sign-on).

### Turn on SCIM

1.  In the Okta Admin Console, open the DraftPilot app.
2.  On the **General** tab, under **App Settings**, click **Edit**, set **Provisioning** to **SCIM**, and click **Save**.

### Connect to DraftPilot

1.  Open the **Provisioning** tab, select **Integration**, and click **Edit**.
2.  Enter:
    -   **SCIM connector base URL:** your DraftPilot SCIM endpoint URL
    -   **Unique identifier field for users:** `userName`
    -   **Supported provisioning actions:** **Push New Users** and **Push Profile Updates**. **Import New Users and Profile Updates** is optional. Leave **Push Groups** off.
    -   **Authentication Mode:** **HTTP Header**
    -   **Authorization:** your DraftPilot SCIM token
3.  Click **Test Connector Configuration**, close the result, and click **Save**.

### Choose what Okta does

1.  On the **Provisioning** tab, select **To App** and click **Edit**.
2.  Enable **Create Users**, **Update User Attributes** and **Deactivate Users**, and click **Save**.
3.  In the attribute mappings on the same page, map `department` to the Okta value you want to drive workspace access, for example `user.department`. If there's no `department` attribute, add it in **Profile Editor** with the external namespace `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`.

### Assign users

1.  Open the **Assignments** tab.
2.  Assign a test user first and check they appear on DraftPilot's [Users page](https://app.draftpilot.ai/users).
3.  Then assign the rest of your people or groups.

Unassigning a user, or deactivating them in Okta, suspends their DraftPilot account.

## Give groups access to workspaces and personas

DraftPilot assigns access from the **department** value your identity provider sends for each user (the SCIM enterprise `department` attribute). It doesn't read SCIM group memberships, so the department value is what links a directory group to DraftPilot access.

### Add a mapping

1.  On the **SCIM provisioning** tab, go to **Group access mappings**.
2.  In **Group value (department)**, enter the department exactly as your identity provider sends it, for example `Legal`. Case doesn't matter.
3.  Choose a **Workspace** and a **Role**: **Viewer** or **Editor**.
4.  If your organization uses personas, choose a **Persona** too, or leave **No persona**.
5.  Click **Add mapping**.

To give the same department more workspaces, click **+ Add workspace** under it. Each department can have one persona. **Remove group** deletes all of a department's mappings.

### How mappings are applied

-   **New user whose department matches:** joins every mapped workspace with the mapped role, and gets the mapped persona. They don't join the default workspace.
-   **New user with no matching department:** joins your organization's default workspace as a **Viewer**, unless DraftPilot support has turned default workspace assignment off for your organization.
-   **Department changes later:** when your identity provider sends the change, the user is added to the new department's workspaces, and their persona changes to the new department's persona if it has one.
-   **Workspace access is only ever added.** Changing a department, or removing a mapping, doesn't take anyone out of a workspace. Remove access on the Users page, or suspend the user from your directory.

Mappings take effect when a user is created and whenever your identity provider sends their department. If you add a mapping after users are provisioned, they pick it up the next time their department is sent, for example after you change it or restart provisioning.

### Getting group membership into the department

By default, Entra ID sends the user's **Department** profile field, and Okta sends whatever you mapped to `department`. If your groups don't line up with departments:

-   In **Entra ID**, you can define app roles on the DraftPilot application, assign groups to those roles, and change the `department` mapping's source to the expression `SingleAppRoleAssignment([appRoleAssignments])`. Each user then sends the role their group gives them. A user can send only one value, so give each user one role.
-   In **Okta**, map `department` from an expression that returns the value you want for each group.

## What happens to accounts

| In your directory | In DraftPilot |
| --- | --- |
| User assigned to the app | Account created (or an existing one with the same email taken over), welcome email sent, workspaces and persona applied |
| Name or email changed | Name updated. Email updated from `userName` (Entra ID) or `emails` (Okta). If an admin has given the user a different display name in DraftPilot, that name is kept. |
| Department changed | New mapped workspaces added, and the new department's persona applied |
| User unassigned, disabled or deleted | Account suspended. The user loses access straight away. Their work is kept. |
| User assigned or enabled again | Account reactivated |

SCIM never deletes a DraftPilot account. It only suspends it.

## Troubleshooting

### Test connection fails with "Invalid token"

-   The token was copied incompletely, or it has been regenerated since. Copy the current token from the **SCIM provisioning** tab.
-   The Tenant URL is for the wrong region. A token only works with its own region's URL.

### "SCIM provisioning is not enabled for this organization"

SCIM isn't on your plan. Email [support@draftpilot.ai](mailto:support@draftpilot.ai) to enable it.

### "Invalid email format"

The user has no valid email address in the `emails` or `userName` attribute. Check the user's `mail` and UPN in your directory.

### A user didn't land in the expected workspace

-   Check the department value your identity provider sent. In Entra ID, **Provision on demand** shows the attributes it sends. It must match the **Group value (department)** in DraftPilot, ignoring case.
-   If the user was provisioned before you added the mapping, their department needs to be sent again.
-   Mappings only add access. A user who was already in the default workspace stays there.

### Provisioning logs show "Remove operation not supported"

DraftPilot doesn't support SCIM `remove` operations, which some identity providers send when an attribute is cleared in the directory. The account itself isn't affected. Set the attribute to a value rather than clearing it, or ignore the error if the attribute doesn't matter to DraftPilot.

### Provisioned users are asked for a password

Provisioned users get your organization's default sign-in method. If they should use SSO, set up [SAML single sign-on](/knowledge-base/saml-and-okta-single-sign-on) and use **Migrate users to SSO** on the **Single sign-on (SSO)** tab, then ask [support@draftpilot.ai](mailto:support@draftpilot.ai) to set your default sign-in method to SAML single sign-on so new users start on SSO.

### Admins can't invite users any more

That's expected once SCIM is active: your directory decides who has an account. Assign the person to the app in your identity provider instead. If you need manual invitations back, contact support.

## Need help?

Email [support@draftpilot.ai](mailto:support@draftpilot.ai) with your organization name, your identity provider, and the error from its provisioning logs. Never send your SCIM token. If you think it has been exposed, regenerate it.