Skip to content

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, *, 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. 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
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, q=None, search_fields=None, first_name=None, last_name=None, username=None, email=None, unique_id=None, is_service_account=None, platform_role=None, permissive=None, sort=None, direction=None, include_total=None, cursor=None, pending=False, **kwargs)

List users visible to the authenticated caller.

Platform administrators see the full directory with email and platform roles. 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.

platform_role filtering and sort/search_fields/q on email are administrator only; other callers receive 403 from the API.

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
cursor str

Continuation token from a previous result's next_cursor; the listing resumes there.

None
q str

Case-insensitive substring search across the fields named in search_fields, or name, username, and unique_id

None
search_fields list or str

Fields searched by q. One or more of first_name, last_name, username, unique_id, email. Requires q

None
first_name str

First-name filter, permissive substring unless permissive=False

None
last_name str

Last-name filter, permissive substring unless permissive=False

None
username str or list

Exact username filter; up to 100 values, case-insensitive. Searches every user

None
email str

Exact email filter. Searches every user

None
unique_id str or list

Exact ORCID or MFID filter; up to 100 values. Searches every user

None
is_service_account bool

Restrict to service accounts or human users

None
platform_role list or str

Platform-role filter. One or more of none, contributor, admin. Administrator only

None
permissive bool

Substring (True, default) or exact matching for first_name and last_name

None
sort str

One of name, username, unique_id, email. Omitted keeps the API's last-name, first-name order

None
direction str

asc (default) or desc

None
include_total bool

True always computes the total, False omits it, None preserves the API default

None
pending bool

List only accounts waiting for approval, with pending_at and sign_in_methods. Platform administrators only

False

Returns:

Type Description
List[Dict]

List[Dict]: User records in the API's requested order

Example

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

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

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

Open to all authenticated users and searches every user. Built on the exact filters of list(), in batches of 100 values (one request per email). Users that match nothing are left out.

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 user record.

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 Union[User, Dict]

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_ref, **kwargs)

Partially update a user record.

Requires admin permissions.

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID or MFID

required
**kwargs Any

Fields to update. Accepted: first_name, last_name, email, username.

{}

Returns:

Name Type Description
Dict Dict

Updated user object

approve(user_ref)

Let in an account that waits for approval. Platform administrators only.

Parameters:

Name Type Description Default
user_ref str

ORCID, MFID, or username of the waiting account, as listed by list(pending=True)

required

Returns:

Name Type Description
Dict Dict

The approved UserRead

Raises:

Type Description
HTTPError 404

No such account.

HTTPError 409

not_pending, the account is not waiting.

reject(user_ref)

Delete an account that waits for approval, freeing its username and login. Platform administrators only.

Approved accounts are never deleted.

Parameters:

Name Type Description Default
user_ref str

ORCID, MFID, or username of the waiting account, as listed by list(pending=True)

required

Raises:

Type Description
HTTPError 404

No such account.

HTTPError 409

not_pending, or still_referenced when other records point at the account.

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_ref)

List access group names for a user.

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID or MFID

required

Returns:

Type Description
List[str]

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

list_projects(user_ref, limit=DEFAULT_LIMIT, offset=0, role=None, sort=None, direction=None, include_metadata=False, cursor=None)

List the projects a user is a member of, with that user's role.

Unlike client.projects.list(member_ref=...), whose role is the caller's, each project's role here is the listed user's.

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID or MFID

required
limit int

Maximum number of results to return (default: 100). Pass None to fetch all.

DEFAULT_LIMIT
offset int

Starting position in the full result set (default: 0)

0
cursor str

Continuation token from a previous result's next_cursor; the listing resumes there.

None
role Optional[Union[str, Sequence[str]]]

Only projects where the user holds one of these roles, from crucible.constants.PROJECT_ACCESS_ROLES.

None
sort Optional[str]

One of crucible.constants.PROJECT_SORTS.

None
direction Optional[str]

asc or desc. Requires sort.

None
include_metadata bool

Include each project's scientific metadata.

False

Returns:

Type Description
List[Dict]

List[Dict]: Project objects the user is a member of

set_platform_role(user_ref, platform_role)

Change a human user's platform role.

Requires human platform-administrator permissions. Service-account callers are rejected even when they hold platform_role=admin, callers cannot change their own role, and service-account targets return 409 pointing at client.service_accounts.set_platform_role(). Demoting the last human platform administrator returns 409.

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID or MFID

required
platform_role str

One of crucible.constants.PLATFORM_ROLES (none, contributor, admin)

required

Returns:

Name Type Description
Dict Dict

Updated UserRead with platform_role and user_capabilities

list_api_keys(user_ref, state='active', limit=DEFAULT_LIMIT, cursor=None)

List a person's API keys, never the keys themselves. Platform administrators only.

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID, MFID, or username

required
state str

'active', or 'inactive' for expired and revoked keys.

'active'
limit Optional[int]

Maximum number of keys. None fetches all.

DEFAULT_LIMIT
cursor Optional[str]

Continuation token from a previous result's next_cursor.

None

Returns:

Type Description
ListResult

ListResult[Dict]: ApiKeyInfo records, newest first.

revoke_api_key(user_ref, key_id)

Revoke one of a person's API keys. Platform administrators only.

Another human administrator's keys need a recent sign-in, not an API key (403 hub_session_required).

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID, MFID, or username

required
key_id int

The key's id from list_api_keys()

required

Raises:

Type Description
HTTPError 404

The key is not one of this person's.

revoke_api_keys(user_ref)

Revoke every API key held by a user, in one atomic call. Platform administrators only.

The user's keys stop authenticating within the API's principal-cache TTL. Works for human users and service accounts. To revoke one key, use revoke_api_key().

Parameters:

Name Type Description Default
user_ref str

Canonical user ORCID or MFID

required