Set up user provisioning via SCIM 2.0 (Entra ID, Okta)
A guide for the UnSpot administrator and the identity provider administrator: how to set up employee provisioning into UnSpot with the SCIM 2.0 standard. It works with Microsoft Entra ID (formerly Azure AD), Okta, OneLogin and any other directory that supports SCIM 2.0. You switch it on in Manage > Integrations > Synchronisations. How the exchange works, what the issued token grants and what is stored on the UnSpot side is covered in the companion article User provisioning via SCIM 2.0: how it works — that is also the one to hand to your information security team.
What you need
- An UnSpot role: Super Administrator or Integrations Administrator.
- Administrator rights in your identity provider — to create an enterprise application and configure provisioning.
- A decision on welcome emails: whether to send them to employees created through SCIM. The toggle is set when connecting.
- A decision on token validity: No limit, or from 1 to 24 months.
- An outgoing subscription to the “Synchronisation issues” event — without it nobody receives the token expiry warning. Set it up in Manage > Integrations > Outgoing webhooks.
SCIM needs no synchronization slot of its own: it works independently of connections to AD LDAP, Entra ID and Google Workspace. Switching SCIM on alongside one of them is not advisable, though — the directory would then have two sources of truth.
Step 1. Switch SCIM on in UnSpot
- Open Manage > Integrations > Synchronisations and click Connect on the SCIM 2.0 card.
- Copy the SCIM URL (in the form
https://your-domain.unspot.com/api/scim) and the token — you will enter both in your identity provider settings. - Set Validity period of the token: No limit or from 1 to 24 months.
- If needed, switch on Send welcome emails — employees created through SCIM will receive an email with brief instructions. ⚠️ If you later change the token validity in this window, explicitly click the email toggle to the position you want as your last action: changing the validity without touching the toggle switches the emails on.
Save the token straight away. It is shown once, when the connection is created, and cannot be retrieved afterwards. Anyone holding it can not only create employees but also read the entire directory of your workspace.
Validity and the welcome-email toggle can only be set at connection time. Once the dialog is closed there is no way back to those settings through the interface — the card keeps only the Disconnect button.
Step 2. Configure Microsoft Entra ID
- Open the Microsoft Entra admin center and create an Enterprise application.
- In the application menu choose Provisioning and the Automatic mode.
- Paste the SCIM URL from UnSpot into Tenant URL and the token into Secret token, then click Test Connection and wait for it to succeed.
- Save the provisioning settings.
Attribute mapping
- In Provision Microsoft Entra ID Groups open “Show advanced options” then Edit attribute list and review the group attributes.
- In Provision Microsoft Entra ID Users replace the source attribute
mailNicknamewithobjectId— it maps toexternalIdin UnSpot.
The resulting set of source user attributes:
userPrincipalNameSwitch([IsSoftDeleted], "False", "True", "True", "False")jobTitlegivenNamesurnametelephoneNumberobjectIddepartment
Send the phone number with the work type — UnSpot rejects other types. Note as well that deactivating an employee who holds an administrator role in UnSpot through SCIM has no effect: such users are deactivated by hand.
Sync scope
- Sync only assigned users and groups: assign users and groups to the application (Users and Groups), then pick that option in Provisioning and start it.
- Sync all users and groups: pick that option in Provisioning, save and start it.
Step 2 (alternative). Okta and other SCIM 2.0 providers
UnSpot works with any identity provider that supports SCIM 2.0 with Bearer token authorization: Okta, OneLogin and others. The logic is the same: in the provisioning settings of the application, set the SCIM URL from UnSpot as the base address and the token as the Bearer credentials, then configure attribute mapping and sync scope.
| Requirement | Value |
|---|---|
| Employee address | sent in userName |
| Content type header | write operations require Content-Type: application/scim+json; with application/json the request is rejected |
| Authorization scheme | Bearer — case-sensitive |
| Group members | addressed by UnSpot identifiers, not by the external identifiers of your directory. An unknown identifier causes an error |
| Phone | the work type only |
If your local Active Directory has no direct access to UnSpot, use an intermediate service instead — an on-premises LDAP-SCIM connector; ask UnSpot support for its setup guide.
What happens during synchronization
- New users within the sync scope are created in UnSpot — with a welcome email when the toggle is on.
- If the directory is already populated: no duplicates are created — the provider links an existing record with a
userName(email) lookup, and an archived record is restored by the create request with the data it carries. - Profile changes (name, position, phone, department) are applied automatically.
- Users marked inactive in the directory are deactivated in UnSpot: their bookings are cancelled, sessions and calendars removed, assigned desks, parking and delegate rights released.
- Users deleted in the directory are archived — on top of the above, the external identifier is cleared and the employee is removed from every group and team.
- Groups are created and their membership is kept current.
- The organizational structure is transferred one way, from the directory into UnSpot. It is a full replacement of the tree: departments missing from the set you send are deleted together with their branch. The operation is available at most once an hour.
Token validity
The SCIM 2.0 card shows the token state: the termination date and the days remaining, or No Limit.
The warning arrives only on the day of expiry and only to the recipients of the outgoing subscription to the “Synchronisation issues” event. There is no week-ahead notice. If the subscription is not set up, the notification reaches nobody — configure it in advance in Manage > Integrations > Outgoing webhooks.
After expiry the card reads that the token was abolished and every call from your directory is refused. There is no separate “reissue token” operation: click Disconnect, connect SCIM again, and then update the token in your identity provider settings.
Disconnecting SCIM clears the external identifiers of every employee and group in the workspace. After reconnecting, your directory matches objects to UnSpot records again by email address. Plan a reissue as maintenance.
SCIM API reference
The endpoints are described in full, with request and response examples, in UnSpot SCIM API reference. In brief:
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/scim/Schemas | SCIM schema definitions |
| GET / POST | /api/scim/Users | List and create users |
| GET / PUT / PATCH / DELETE | /api/scim/Users/{id} | Read and modify a user |
| POST | /api/scim/Users/{id}/avatar | Upload an avatar (JPEG or PNG, up to 100 KB) |
| GET / POST | /api/scim/Groups | List and create groups |
| GET / PUT / PATCH / DELETE | /api/scim/Groups/{id} | Read and modify a group |
| PUT | /api/scim/OrgUnits | Upload the organizational structure |
If something does not work
| What you see | Why | What to do |
|---|---|---|
| Refused with code 401 | The token is missing or wrong, or the authorization scheme is written in a different case | Check the authorization header in the provider settings: the scheme is written as Bearer, with a capital letter |
| Refused with code 400 and a message about an expired token | The token validity has ended. Note that it is 400, not 401 — many providers surface this as a bad request | Disconnect SCIM and connect it again, then update the token in the provider settings |
| Refused with code 415 | A write operation was sent with Content-Type: application/json | Use application/scim+json |
| An error mentioning externalId when creating a user | That external identifier is already used by another record | Check the objectId to externalId mapping on the directory side |
| The error “This userName is already used” | A record with this email already exists and is not archived | Do not create it again: the provider should find the record with GET /Users?filter=userName eq … and link it; an archived record is restored by the create request itself |
| An error saying the manager is not correct | The manager was not found in UnSpot | Make sure the manager record is created before their reports |
| Deleting an employee is rejected with a message about a connected calendar | The employee personal calendar is connected to a meeting room | Disconnect the employee calendar from the room and retry the request |
| An error when adding a member to a group | Members are addressed by UnSpot identifiers, not by the external identifiers of your directory | Check that every member already exists in UnSpot |
| The organizational structure upload is refused with a message to try later | The operation is available at most once an hour | Repeat later |
| Departments disappeared from UnSpot | Uploading the structure is a full replacement of the tree: nodes missing from the set are deleted | Send the whole tree rather than the part that changed |
| Deactivating an administrator has no effect | For a user holding an administrator role in UnSpot the operation is ignored | Deactivate such an employee by hand in UnSpot |
| Provisioning errors in Entra ID | An attribute failed validation | Open the provisioning logs in the Entra admin center — they show which one |
On the UnSpot side, look at Analytics > Reports, the User management history report: SCIM operations carry the matching marker on the initiator. The History of Integration Management report does not record SCIM events.
UnSpot does not surface provisioning errors in the console — read them on the provider side: the Provisioning logs in Entra ID or the Okta system log. Per the provider documentation, the Entra ID cycle starts roughly every 40 minutes and Okta works in near real time — a pause of that scale is not a failure. A quick check that the address and the token are alive: GET {SCIM URL}/Users?count=1 with the Authorization: Bearer <token> header should return 200 with a one-user list.
