SCIM provisioning lets your identity provider (IdP), such as Okta or Microsoft Entra ID, manage your Four/Four team for you. Four/Four implements SCIM 2.0 (RFC 7643 and RFC 7644). When people join, change role, move team or leave in your IdP, the change is applied in Four/Four automatically. Four/Four never writes anything back to your IdP.
With SCIM you can:
Create users when they are assigned to the Four/Four application in your IdP. They are added as accepted team members, so no invitation email is sent.
Set roles from your IdP, using the Four/Four role names (Viewer, Creator, Admin or any custom role).
Manage groups. Groups pushed from your IdP are created as Four/Four team groups, with their members kept in step.
Remove users from Four/Four when they are unassigned or deactivated in your IdP.
Before you begin
You need the Manage connections permission in Four/Four to generate the SCIM token, and administrator access to your IdP.
SCIM users never have a password. They sign in with single sign-on, so set up SSO first.
The SCIM token acts as the person who generated it, and that person needs the Manage team permission. SCIM stops working if they lose that permission or are removed from the team.
Set up in Four/Four
Sign in as the account that will own the token and go to Admin > Connections.
Scroll to Authentication & governance and click Connect on the SCIM Provisioning card.
Copy the SCIM base URL.
Click Generate token and copy the Bearer token. It is shown once, so store it somewhere safe such as your password manager. It is a personal access token with the SCIM scope and is valid for one year.
Generated tokens are listed in the Personal tokens section of the same page, where you can revoke them if needed.
Configure your identity provider
Every IdP will need:
Base URL: the SCIM base URL you copied.
Authentication type: Bearer token (sometimes labelled API token, secret token or OAuth bearer token): the token you generated.
Unique identifier: which should be the IdP-side unique id such as the Entra objectId.
Most IdPs also need you to enable Create, Update and Deactivate (or Delete) for users, and to turn on group push if you want groups. Menu names change from time to time, so treat the outlines below as a guide.
Okta
In the Okta Admin Console, add the SCIM 2.0 Test App (Header Auth) from the app catalog, or use your own SCIM application, and assign the people and groups who should be provisioned.
On the Provisioning tab choose Configure API Integration and enable it.
Enter the SCIM base URL, set the unique identifier field to userName, and paste the bearer token as the authorization header value. Click Test Connector Configuration, then Save.
Under Provisioning > To App enable Create Users, Update User Attributes and Deactivate Users.
Make sure externalId is mapped to a value that never changes, such as the Okta user ID, and that email is mapped to the user's email address. To send roles, add a roles attribute to the application profile and map it as described under Roles below.
To provision groups, use the Push Groups tab and add the groups you want.
Microsoft Entra ID
In the Entra admin center go to Enterprise applications > New application > Create your own application and choose a non-gallery application.
Open Provisioning.
Under Connectivity enter the SCIM base URL as the Tenant URL and the bearer token as the Secret Token, then click Test Connection and Save.
Under Attribute mapping, set the attribute mappings in the table below. The most important change from Entra's defaults is to map objectId to externalId.
Enable Provision Microsoft Entra ID Groups if you want groups, and check that displayName maps to displayName, objectId to externalId and members to members.
Assign users and groups, then set Provisioning Status to On.
Sample user attribute mappings
IdP attribute | Four/Four SCIM attribute | Notes |
userPrincipalName | userName | Required. Four/Four uniquely identifies users by email address. If your users' UPNs are not their email addresses, map mail to userName instead. |
objectId | externalId | Required. |
displayName | displayName | Used as the user's name when the account is created. |
appRoleAssignments | roles | Optional. See Roles. |
Other attributes IdPs can send, such as job title, phone numbers and the manager, are ignored.
Other providers
Any provider that supports SCIM 2.0 with a bearer token can be used, including OneLogin and JumpCloud. Use the same values as above.
User lifecycle
Provisioning: when a user is assigned in your IdP they are added to Four/Four as an accepted team member. No invitation email is sent, and they have no licences until you assign them under Admin > Team. Licences cannot be set through SCIM at this time.
Existing users: if the person is already on your team, your IdP finds them by email and links them to its record. Their licences and groups are kept. Their roles will be kept if you are not sending the 'roles' attribute. Essentially the IdP 'takes control' of existing users and groups, and manages them from then on.
Updates: changes to the external ID, roles and group membership are applied.
Deprovisioning: when a user is unassigned, deactivated or deleted in your IdP, they are removed from your Four/Four team and lose access to your workspace. Their roles, licences and group memberships are removed with them, and their personal access tokens for your workspace are revoked. If you later assign them again they are created afresh as a Viewer with no licences.
Managed in your IdP: a user with an external ID is managed by your IdP. In Four/Four you can see their roles and external ID, but you cannot change their roles or remove them under Admin > Team. Make those changes in your IdP. Licences, job domain and notetaker settings can still be changed in Four/Four.
Roles
Roles are set with the standard SCIM roles attribute on the user. Each entry's value is the name of a Four/Four role, spelled exactly as it appears under Admin > Roles: Viewer, Creator, Admin, or the name of any custom role you have created.
For example, this gives a user the Creator and Admin roles:
"roles": [{ "value": "Creator" }, { "value": "Admin" }] New users who arrive with no roles are given Viewer.
Changing roles: the roles you send replace the user's current roles. A user who is sent no roles at all keeps the roles they already have, so an IdP that does not manage roles will never remove them.
Unknown role names are rejected and the user is not created or changed. Check the spelling and capitalisation against Admin > Roles.
Roles are not taken from groups. Four/Four groups are team groups for organising people and do not grant permissions.
Mapping roles in your IdP
Okta: add a roles attribute to the application profile and map it, for example with an expression, to the role names you want. Okta sends the value as the SCIM roles attribute.
Microsoft Entra ID: define app roles on the application whose display names match the Four/Four role names, assign users to those app roles, and keep the roles mapping on the user provisioning mappings. Entra's default roles mapping sends the assigned app roles.
Groups
Groups pushed from your IdP appear in Four/Four as team groups, under Admin > Groups.
IdP attribute | Four/Four attribute | Notes |
displayName | displayName | Required. Group names must be unique, ignoring upper and lower case. Renaming a group in your IdP renames it in Four/Four. |
externalId/objectId | externalId | Required when a group is created. |
members | members | Every member must already be on your team, so users are provisioned before the groups that contain them. Adding or removing a member in your IdP does the same in Four/Four. |
If a group with the same name already exists in Four/Four, your IdP finds it by name and takes it over rather than creating a duplicate.
Deleting a group in your IdP, or removing it from the push list, deletes the group in Four/Four. Users in the group are not affected.
Removing a user from your IdP also removes them from every group.
Managed in your IdP: a group with an external ID cannot be renamed, deleted or have its members changed in Four/Four. You can still see its external ID and members under Admin > Groups. Make those changes in your IdP.
Test the connection
Assign a test user in your IdP, with a role such as Creator if you are sending roles.
Check Admin > Team in Four/Four. The user should appear within a few minutes with the role you set.
Push a test group containing that user and check Admin > Groups.
Change the test user's role in your IdP and confirm it changes in Four/Four.
Unassign the test user and confirm they are removed.
Rotating the token
On the SCIM Provisioning card click Connect and Generate token to create a new token.
Paste the new token into your IdP's provisioning settings and test the connection.
Revoke the old token under Personal tokens.
Tokens expire after one year, so rotate before then. Revoking a token stops provisioning that uses it immediately.
Troubleshooting
What your IdP reports | Cause and fix |
401 Unauthorized or "Authentication required" | The token is wrong, expired or revoked, or the person who owns it has been removed from the team. Generate a new token and update your IdP. |
403 Forbidden | The token owner no longer has the Manage team permission, or the request tried to change the token owner's own account. Use a dedicated administrator account that is not assigned to the application in your IdP. |
412 "Plan is not active" | Your Four/Four plan is not active. Contact support. |
400 "externalId is required" | Map externalId to a stable unique value in your IdP's attribute mappings, for users and for groups. In Entra, map objectId to externalId. |
400 "Unknown role" | A role name does not match a role in Admin > Roles. Role names must match exactly. |
400 "Group members must be users in this tenant" | A group contains someone who has not been provisioned. Assign the user to the application first, then push the group again. |
400 "userName cannot be changed" | The email address changed in your IdP. Remove the user, then provision them again with the new address. |
400 invalid filter | Four/Four supports only equality filters: userName or externalId for users, and displayName or externalId for groups. |
409 Conflict | The user is already on your team, or the group name or external ID is already in use. Most IdPs then link to the existing record. If yours does not, check for a duplicate name or ID. |
429 Too Many Requests | A token is limited to 600 requests a minute. Your IdP retries automatically. |
If users are not appearing and you see no error, check that provisioning is switched on in your IdP, that the user or group is assigned to the application, and your IdP's provisioning log, which shows each request and the response from Four/Four.
What is not supported via SCIM
Licences. Assign them under Admin > Team.
Passwords and password changes. SCIM users sign in with single sign-on.
Name changes after the account is created.
Bulk operations, sorting and ETags.
Filters other than equality on the attributes listed above. Lists are returned up to 100 at a time.
Security
Treat the bearer token like a password: only IdP administrators should have it.
Use a dedicated administrator account to own the token, and rotate the token at least once a year.
Revoke the token under Personal tokens if it may have been exposed.
Review your IdP's provisioning logs regularly.
Permissions
Generating or revoking the SCIM token needs the Manage connections permission. SCIM requests only succeed while the person who owns the token has the Manage team permission.
Need a hand? Contact support from the chat on this help center.