UserOperations

Access via client.users.

Note

Most user management operations require admin privileges.

For self-service profile and API key operations see client.account.

crucible.resources.users.UserOperations

User-related API operations.

Access via: client.users.get(), client.users.create(), etc.

get(user_ref=None, email=None, username=None, *, orcid=None, user_unique_id=None)

Get a user by canonical unique ID, username, or email.

Username and email references use exact collection filters and return the caller-authorized representation without a second request. Self and platform-administrator lookups may include email; other callers receive the public-safe representation. orcid, email, and username remain supported keyword forms.

Parameters:

Name	Type	Description	Default
user_ref	str	ORCID, user MFID, username, or email	None
email	str	User's email address	None
username	str	User's username	None
orcid	str	Explicit person ORCID	None
user_unique_id	str	Explicit canonical ORCID or user MFID	None

Returns:

Name	Type	Description
Dict	Dict	UserRead for a canonical lookup or the exact collection item

Raises:

Type	Description
ValueError	If no identifier or multiple identifiers are provided

search(q, limit=20)

Search for users by name or username. Available to all authenticated users.

Matches the query term against username, first name, and last name simultaneously (case-insensitive). Returns UserPublicRead — no email exposed. Hard-capped at 50 results.

Use client.users.list() for admin-level field-specific filtering.

Parameters:

Name	Type	Description	Default
q	str	Search term (e.g. "fabrice", "ron")	required

Returns:

Type	Description
List[Dict]	List[Dict]: Matching users (username, first_name, last_name, orcid)

list(limit=DEFAULT_LIMIT, offset=0, **kwargs)

List users visible to the authenticated caller.

Platform administrators see the full directory. Other callers see users who share an access group with them. Broad collection records are public-safe. Exact unique-ID, username, or email filters may include email when the caller is that user or a platform administrator.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of results to return (default: 100)	DEFAULT_LIMIT
offset	int	Starting position in the full result set (default: 0)	0
**kwargs		Additional query parameters for filtering	{}

Returns:

Type	Description
List[Dict]	List[Dict]: Public-safe user records with canonical identity and name

Example

users = client.users.list(limit=50) for user in users: ... print(f"{user['first_name']} {user['last_name']} ({user['orcid']})")

resolve(user_unique_ids=None, usernames=None, emails=None)

Batch-resolve users by canonical IDs, usernames, or emails.

Open to all authenticated users. Returns public profiles (no email).

Parameters:

Name	Type	Description	Default
user_unique_ids	Optional[List[str]]	List of canonical user ORCIDs or MFIDs	None
usernames	Optional[List[str]]	List of username strings	None
emails	Optional[List[str]]	List of email strings	None

Returns:

Name	Type	Description
Dict	Dict	Mapping of canonical user ID to UserPublicRead.

create(user, project_ids=None)

Create a human user with an ORCID or a server-assigned MFID.

If supplied, the ORCID must be canonical. When it is omitted, the API generates an MFID for the user.

Requires admin permissions.

Parameters:

Name	Type	Description	Default
user		User model or dict with user information. Required fields: first_name, last_name, username. Optional: unique_id/orcid and email. If a dict, may include a 'projects' key (list of project IDs) as an alternative to the project_ids parameter.	required
project_ids	list	Project IDs to associate with the user.	None

Returns:

Name	Type	Description
Dict	Dict	Created or updated user object

Example

from crucible.models import User user = User(first_name="Jane", last_name="Doe", username="jane-doe") new_user = client.users.create(user, project_ids=["project1"])

update(user_unique_id, **kwargs)

Partially update a user record.

Requires admin permissions.

Parameters:

Name	Type	Description	Default
user_unique_id	str	Canonical user ORCID or MFID	required
**kwargs		Fields to update. Accepted: first_name, last_name, email, username.	{}

Returns:

Name	Type	Description
Dict	Dict	Updated user object

list_datasets(user_ref)

List dataset MFIDs accessible to a user.

Inspecting another user requires platform-administrator permissions.

Parameters:

Name	Type	Description	Default
user_ref	str	User MFID, ORCID, username, or email	required

Returns:

Type	Description
List[str]	List[str]: Dataset unique IDs the user has access to

check_dataset_access(user_ref, dataset_mfid)

Return a user's effective access role for a dataset.

Inspecting another user requires platform-administrator permissions.

Parameters:

Name	Type	Description	Default
user_ref	str	User MFID, ORCID, username, or email	required
dataset_mfid	str	Dataset MFID	required

Returns:

Name	Type	Description
EffectiveResourceAccess	EffectiveResourceAccess	Canonical user, resource, and effective role

list_access_groups(user_unique_id)

List access group names for a user.

Parameters:

Name	Type	Description	Default
user_unique_id	str	Canonical user ORCID or MFID	required

Returns:

Type	Description
List[str]	List[str]: Access group names the user belongs to

add_to_access_group(user_unique_id, group_name)

Add a user to an access group.

Requires admin permissions.

Parameters:

Name	Type	Description	Default
user_unique_id	str	Canonical user ORCID or MFID	required
group_name	str	Name of the access group	required

Returns:

Name	Type	Description
Dict	Dict	Updated access group object

remove_from_access_group(user_unique_id, group_name)

Remove a user from an access group.

Requires admin permissions.

Parameters:

Name	Type	Description	Default
user_unique_id	str	Canonical user ORCID or MFID	required
group_name	str	Name of the access group	required

Returns:

Name	Type	Description
Dict	Dict	Response message

verify_api_key(user_unique_id)

Verify the API key for any user. Admin only.

Parameters:

Name	Type	Description	Default
user_unique_id	str	Canonical user ORCID or MFID	required

Returns:

Name	Type	Description
Dict	Dict	{valid: bool, created_at: str, expires_at: str}