Set up SCIM provisioning

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 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.
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 [email protected], 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 [email protected].
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.
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

Sign in to DraftPilot in your browser and open Organization settings > SCIM provisioning.
Under Set up SCIM provisioning, click Generate SCIM token.
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, 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

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

Check the attribute mappings

Open Mappings.
Open Provision Microsoft Entra ID Groups, set Enabled to No, and save. DraftPilot doesn’t use SCIM groups (see Give groups access), so there’s nothing to gain from pushing them.
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

In Provisioning > Settings, set Scope to Sync only assigned users and groups.
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

Click Provision on demand, pick a test user, and click Provision. Entra ID shows each step, and any error DraftPilot returns.
In DraftPilot, open the Users page and check the user appears in the workspaces you expect.
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 instead.

Add provisioning to the DraftPilot SAML app you created for SAML single sign-on.

Turn on SCIM

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

Connect to DraftPilot

Open the Provisioning tab, select Integration, and click Edit.
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
Click Test Connector Configuration, close the result, and click Save.

Choose what Okta does

On the Provisioning tab, select To App and click Edit.
Enable Create Users, Update User Attributes and Deactivate Users, and click Save.
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

Open the Assignments tab.
Assign a test user first and check they appear on DraftPilot’s Users page.
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

On the SCIM provisioning tab, go to Group access mappings.
In Group value (department), enter the department exactly as your identity provider sends it, for example Legal. Case doesn’t matter.
Choose a Workspace and a Role: Viewer or Editor.
If your organization uses personas, choose a Persona too, or leave No persona.
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 [email protected] 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 and use Migrate users to SSO on the Single sign-on (SSO) tab, then ask [email protected] 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 [email protected] 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.