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 |