📖 Table of contents
Overview
System for Cross-domain Identity Management (SCIM) allows your Identity Provider (IdP) to automatically provision, update, and deprovision users in Youtrust.
Once configured, user lifecycle changes made in your IdP, such as onboarding new employees, deactivating users, or changing roles, are automatically reflected in Youtrust.
What SCIM manages in Youtrust
Automatic user provisioning when users are added in your IdP
Automatic user deactivation when users are removed from your IdP
Automatic synchronisation of names and roles to keep Youtrust aligned with your IdP
Owners cannot be created, deactivated, or deleted through SCIM provisioning.
Scope
Supported synchronised attributes:
Role
Group-based provisioning is not currently supported.
Supported Identity Providers
SCIM is supported with Identity Providers that support SCIM 2.0 and can be configured with Youtrust SSO.
Before you start
Before configuring SCIM, make sure you have:
The SCIM and SSO add-on activated on your account
Admin access to Youtrust
Admin access to your Identity Provider
Single Sign-On (SSO) already configured and active on your Youtrust account
SCIM can only be activated after SSO has been configured.
Step 1: Generate your SCIM credentials in Youtrust
Before configuring your Identity Provider, retrieve your SCIM endpoint and generate a token from Youtrust.
Sign in to Youtrust as an admin.
Go to Settings → Access security → SCIM.
Click Activate.
Activating SCIM deletes all pending invitations.
Once SCIM is activated, user information (email address, first name, and last name) and invitations can only be managed through your Identity Provider until SCIM is deactivated.
Copy the SCIM Endpoint URL.
Click Generate token.
Copy and securely store the token immediately. It will not be displayed again.
You can delete and regenerate the token at any time from this page.
Deleting the token invalidates it and temporarily interrupts provisioning until the new token is configured in your IdP.
Step 2: Understand Youtrust roles
The role value sent by your IdP must match one of the following values (case-insensitive).
Role name | IdP attribute value | Description |
Admin | admin | Full access to workspace settings, billing, and user management |
Member | member | Standard user who can send and sign documents |
Send the role using the following SCIM attribute format:
"roles": [ { "value": "admin", "type": "role" } ]Additional parameters are not supported (for example, primary).
If no role is provided, the user is provisioned with the Member role by default.
Step 3: Configure your Identity Provider
Retrieve values from Youtrust
Retrieve the following values before configuring provisioning.
Parameter | Where to find it |
SCIM Base URL | Settings → Access security → SCIM → Endpoint URL |
Bearer Token | Settings → Access security → SCIM → Bearer Token |
Configure SCIM endpoint and authentication
Enter the following values in your IdP.
Setting | Value |
SCIM version | SCIM 2.0 |
Base URL | Your Youtrust SCIM Base URL (without trailing slash) |
Authentication method | HTTP Header — Bearer token |
Token | Your Youtrust Bearer token |
Supported provisioning actions | Push New Users; Push Profile Updates |
Unique identifier field for users | Map to an immutable email attribute in your IdP (typically |
Configure required attribute mappings
Map your IdP attributes to the following SCIM attributes.
SCIM attribute | Expected value | Required |
userName | User's email address (unique, immutable identifier) | Yes |
externalId | User's Unique ID | Yes |
emails[primary eq true].value | User's email address (the email domain must be included in the organization's allowed SSO domains) | Yes |
name.givenName | User's first name | Yes |
name.familyName | User's last name | Yes |
active | true / false — controls activation and deprovisioning | Yes |
roles[type eq "role"].value | One of: admin, member | Recommended |
⚠️ name.givenName and name.familyName must follow these limitations:
Maximum 150 characters
Allowed characters: letters, numbers, spaces, apostrophes, hyphens, parentheses, accented letters
Cannot start or end with a space
Cannot contain 10 consecutive digits
If name.givenName or name.familyName does not match Youtrust's accepted format, those values are ignored during provisioning.
The user account is still created successfully, and the user will complete their information during their first login.
Supported SCIM operations
Enable these operations in your IdP when available.
Operation | Supported | Effect in Youtrust |
Create user (POST /Users) | Yes | Provisions a new user account |
Update user (PATCH /Users/{id}) | Yes | Updates user information and role |
Deactivate user (PATCH active=false) | Yes | Suspends the user |
Delete user (DELETE /Users/{id}) | Yes | Deactivates the user account (data retained) |
Get user (GET /Users/{id}) | Yes | Allows the IdP to verify user existence |
List users (GET /Users) | Yes | Used for reconciliation |
Seat limit behaviour
Youtrust applies seat limits based on your subscription.
If SCIM attempts to provision a user after all seats have been consumed:
The user is not created
Admins and Owners receive an email notification
Provisioning can resume after purchasing seats or deprovisioning users and triggering provisioning again
Verify the setup
After provisioning runs:
Go to Settings → Users in Youtrust.
Verify that users appear with the expected role.
Review provisioning logs in your IdP.
Confirm users can authenticate through SSO successfully.
User experience after provisioning
Users provisioned through SCIM do not receive an invitation. Their account is created automatically and they only need to log in.
Welcome email
When a user is provisioned, they receive an email confirming that their account is ready.
The Log in button redirects to the Youtrust login page
Users sign in with their work email address through SSO
If a user did not receive the email, they can sign in directly from the Youtrust login page.
First login
On their first login, users complete an onboarding screen.
Field | Behaviour |
First name | Prefilled from your IdP and locked. Empty and editable if missing or not in the accepted format |
Last name | Prefilled from your IdP and locked. Empty and editable if missing or not in the accepted format |
Phone number | Optional |
A tooltip on locked fields informs users that this information is managed by their organisation.
Profile information
The following information is managed by your IdP and cannot be edited by users in Youtrust:
Email address
First name
Last name
Role
A banner at the top of the profile page informs users that this information is managed by their admin. To update it, edit the user in your IdP.