User Management

Contract Lucidity supports three types of user accounts: local users (created by an admin with email and password), SSO users (created automatically when a user logs in via a configured identity provider), and SCIM-provisioned users (pushed automatically from an identity provider via SCIM 2.0). All types are managed from Settings > Users in the admin UI.

User Roles

Role	Scope	Description
Admin	Global	Full access to all projects, settings, users, groups, playbook, and AI configuration
User	Project-level	Can only see projects they have been explicitly granted access to (or the default project)

info

Role determines what actions a user can perform. Project access (covered in Groups & Access Control) determines which projects a user can see.

Creating Local Users

Only admins can create local user accounts. Navigate to Settings > Users and click Add User.

Required fields:

Field	Description
Email	Must be unique across all users (local and SSO)
First Name	Display name
Last Name	Display name
Password	Initial password for the user
Role	admin or user (default: user)

New local users are created with must_change_password=True, meaning they will be prompted to set a new password on first login.

tip

If you plan to enable SSO later, you can pre-create users with matching email addresses. When those users log in via SSO for the first time, their existing local account will be automatically linked to the SSO identity.

SCIM-Provisioned Users

When SCIM provisioning is enabled (see SSO & SCIM Setup), your identity provider can automatically push user accounts to Contract Lucidity. SCIM-provisioned users have the following characteristics:

Property	Value
is_sso_user	true
sso_provider	The provider name from SSO config (e.g., Azure AD, Okta)
sso_subject_id	The externalId from the SCIM payload
Password	No password stored (SSO_USER_NO_PASSWORD) -- they authenticate via SSO
must_change_password	false
Role	user (default) -- admins can change this after provisioning

Email Matching and Account Linking

When the IdP pushes a user via SCIM whose email matches an existing CL account:

• The existing account is linked to the SSO identity rather than creating a duplicate
• The existing account's is_sso_user flag is set to true
• The sso_provider and sso_subject_id fields are populated
• The user's first and last name are updated from the SCIM payload (if provided)

This means you can pre-create accounts in CL before enabling SCIM, and the accounts will be linked automatically when the IdP first syncs.

How SCIM Users Appear in the UI

SCIM-provisioned users appear in the Settings > Users list alongside local and SSO users. They can be identified by:

• The SSO badge or column showing is_sso_user = true
• The SSO Provider column showing the provider name

Admins can still edit SCIM-provisioned users' roles and active status through the CL admin UI. However, name and email changes should be made in the identity provider, as the next SCIM sync will overwrite local changes to those fields.

Activating and Deactivating Users

Admins can toggle a user's active status from the user list. Deactivated users:

• Cannot log in (local or SSO)
• Are not deleted from the system -- their data and audit trail are preserved
• Can be reactivated at any time

warning

You cannot deactivate your own admin account. This safeguard prevents accidental lockout.

The Users panel has two tabs: Active (default) and Deactivated. Deactivated users can be reactivated from the Deactivated tab. There is no permanent delete — all removals are soft-deletes that preserve audit trails and document associations. SCIM deprovisioning (when a user is removed from the app assignment in the IdP) also performs a soft-delete.

Seed Admin Protection

Contract Lucidity creates a default administrator account on first boot (configured via DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD environment variables). This seed admin account has special protections:

• It is hidden from the Settings > Users list (Security tab) -- other admins cannot see or modify it
• It cannot be edited or deactivated through the admin API
• It serves as a break-glass account for recovery if all other admin accounts are locked out

The seed admin can still log in and manage the system normally. Only the seed admin's email and password (set via environment variables) can be used to access this account.

tip

Always keep the seed admin credentials in a secure location. If you lose access to all admin accounts, the seed admin is your recovery path.

SSO Users vs Local Users

Aspect	Local User	SSO / SCIM User
Created by	Admin via UI or API	SSO: auto on first login. SCIM: pushed from IdP
Password	Stored as bcrypt hash	No password stored (SSO_USER_NO_PASSWORD)
Login method	Email + password	Identity provider redirect (OIDC)
MFA	Not built in (use SSO for MFA)	Handled by the identity provider
is_sso_user flag	false	true
sso_provider	null	Provider name (e.g., Azure AD)
Lifecycle management	Manual via admin UI	Automatic via SCIM or manual via admin UI

SSO users are identified by the combination of sso_provider and sso_subject_id (the sub claim from the OIDC token, or externalId from SCIM). If an SSO user's email matches an existing local account, the accounts are linked automatically.

Self-Service Profile Editing

All users (not just admins) can update their own profile by navigating to the Profile tab (accessible from the user menu). Users can edit:

• First Name
• Last Name
• Email (must be unique -- the system checks for conflicts)

Users cannot change their own role or active status. Those fields can only be modified by an admin.

The self-service profile endpoint is PATCH /api/users/me.

Editing Users (Admin)

Admins can update the following fields on any user (except the seed admin):

• First Name and Last Name
• Role (admin or user)
• Active status (activate/deactivate)

Email addresses and SSO linkage cannot be changed by admins after creation.

Individual User Deny Permissions

In addition to allow grants, individual users can have deny permissions on specific projects. A deny permission blocks all access to the project regardless of any allow grants the user has (directly or through groups).

User Permission vs Group Permission Precedence

Permissions are resolved in the following order (first match wins):

1. Ethical wall deny -- Overrides everything (except seed admin)
2. User deny -- An explicit deny on the user blocks access even if a group allows it
3. Group deny -- A deny from any group blocks access even if the user has a direct allow
4. User allow -- A direct allow grant at the specified level
5. Group allow (highest) -- The most permissive allow level across all the user's groups
6. Default deny -- No permission found means no access

Note that a user deny takes precedence over a group allow, and a group deny takes precedence over a user allow. The hierarchy strictly follows the deny-before-allow principle.

Checking Effective Permissions

Admins can check what a user's effective permission is for any project, accounting for all direct grants, group grants, and ethical walls:

Method	Endpoint	Description
GET	/api/admin/users/:user_id/effective-permissions	List effective permissions across all projects
GET	/api/admin/users/:user_id/effective-permissions/:project_id	Check effective permission for a specific project

The response includes the resolved permission level (or denied), the source of the permission (direct grant, group name, ethical wall name), and whether a deny is active.

API Reference

Admin User Management Endpoints (require admin auth)

Method	Endpoint	Description
GET	/api/admin/users	List all users with group memberships (excludes seed admin)
GET	/api/admin/users/search	Search users by name or email (paginated)
POST	/api/admin/users	Create a new local user
PATCH	/api/admin/users/{user_id}	Update user fields
DELETE	/api/admin/users/{user_id}	Soft-delete (deactivate) a user

Self-Service Endpoints (require user auth)

Method	Endpoint	Description
GET	/api/users/me	Get your own profile
PATCH	/api/users/me	Update your own first name, last name, or email