Skip to content

AccessGroupOperations

Access via client.access_groups. Project join requests: any signed-in user can ask to join a project, follow the request, and withdraw it. Project editors and above, and platform administrators, review requests and choose the role to grant, which must be below their own.

req = client.access_groups.request_join("thin-films", reason="XRD campaign")

queue = client.access_groups.list_join_requests(scope="reviewable", status="pending")
client.access_groups.approve_join_request(queue[0]["id"], role="viewer")

counts = client.access_groups.join_request_facets("project", scope="reviewable", status="pending")

crucible.resources.access_groups.AccessGroupOperations

Operations for the project join-request workflow.

Access via: client.access_groups.*

request_join(project_ref, reason=None)

Request to join a project. Any signed-in user who is not a member.

Parameters:

Name Type Description Default
project_ref str

Project slug (project_id) or MFID.

required
reason Optional[str]

Optional explanation for the request (at most 2000 characters).

None

Returns:

Name Type Description
Dict Dict

The created JoinRequest record (status will be "pending").

Raises:

Type Description
HTTPError 404

Project doesn't exist.

HTTPError 409

Already a member, already has a pending request for this project, has too many pending requests, or the project is pending deletion.

list_join_requests(group_name=None, status=None, requester_id=None, limit=DEFAULT_LIMIT, offset=0, privilege_mode=None, cursor=None, scope=None, project_mfid=None, reviewer_id=None, requested_after=None, requested_before=None, reviewed_after=None, reviewed_before=None, q=None, sort=None, direction=None)

List join requests visible to the caller.

Parameters:

Name Type Description Default
group_name Optional[str]

Removed in 4.0.0; passing it raises RemovedError. Use project_mfid.

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

One status or a list of them, from crucible.constants.JOIN_REQUEST_STATUSES.

None
requester_id Optional[str]

Only requests by this user (ORCID or MFID).

None
limit int

Maximum number of results (default 100, max 1000).

DEFAULT_LIMIT
offset int

Starting position in the full result set.

0
privilege_mode Optional[str]

Per-call privilege mode. Defaults to elevated for callers who can elevate, except with scope "submitted".

None
cursor str

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

None
scope Optional[str]

One of crucible.constants.JOIN_REQUEST_SCOPES. The server defaults to "accessible" (your own requests plus those you may review); "submitted" returns only yours and "reviewable" only those you may review.

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

One project MFID or a list of them.

None
reviewer_id Optional[str]

Only requests closed by this user.

None
requested_after Optional[TimeBound]

Only requests made at or after this time (datetime, date, or ISO 8601 string; naive values are UTC).

None
requested_before Optional[TimeBound]

Only requests made before this time.

None
reviewed_after Optional[TimeBound]

Only requests closed at or after this time.

None
reviewed_before Optional[TimeBound]

Only requests closed before this time.

None
q Optional[str]

Matches the requester's name, username, or ORCID.

None
sort Optional[str]

One of crucible.constants.JOIN_REQUEST_SORTS (server default: request_time).

None
direction Optional[str]

"asc" or "desc" (server default: desc).

None

Returns:

Type Description
List[Dict]

List[Dict]: Matching JoinRequest records.

join_request_facets(field, limit=50, scope=None, status=None, project_mfid=None, requester_id=None, reviewer_id=None, requested_after=None, requested_before=None, reviewed_after=None, reviewed_before=None, q=None, privilege_mode=None)

Count join requests by status, project, or requester.

Takes the same scope and filters as list_join_requests(). Buckets are ordered by count, largest first.

Parameters:

Name Type Description Default
field str

One of crucible.constants.JOIN_REQUEST_FACET_FIELDS.

required
limit int

Maximum number of buckets (default 50, max 200).

50

Returns:

Name Type Description
Dict Dict

field, items (buckets with value, label, count, and a project or requester reference where applicable), limit.

get(request_id)

Fetch a single join request by ID.

Visible to its requester, to those who may review it, and to platform admins.

Parameters:

Name Type Description Default
request_id int

Integer id of the JoinRequest.

required

Returns:

Name Type Description
Dict Optional[Dict]

The JoinRequest record, or None if it does not exist or is not visible to the caller.

approve_join_request(request_id, reviewer_notes=None, role=None)

Approve a pending join request. Project editors and above, or admin.

On approval, the requester is added to the project at role.

Parameters:

Name Type Description Default
request_id int

Integer id of the JoinRequest to approve.

required
reviewer_notes Optional[str]

Optional notes explaining the decision.

None
role Optional[str]

Role to grant, one of crucible.constants.PROJECT_MEMBER_ROLES and strictly below your own role in the project. The server defaults to contributor.

None

Returns:

Name Type Description
Dict Dict

The updated JoinRequest record.

Raises:

Type Description
HTTPError 403

Not allowed to review, or the role is not below yours.

HTTPError 409

Request is already closed, or the project is gone or pending deletion.

reject_join_request(request_id, reviewer_notes=None)

Reject a pending join request. Project editors and above, or admin.

No membership change occurs.

Parameters:

Name Type Description Default
request_id int

Integer id of the JoinRequest to reject.

required
reviewer_notes Optional[str]

Optional notes explaining the decision.

None

Returns:

Name Type Description
Dict Dict

The updated JoinRequest record.

Raises:

Type Description
HTTPError 409

Request is already closed.

withdraw_join_request(request_id)

Withdraw your own pending join request.

Parameters:

Name Type Description Default
request_id int

Integer id of the JoinRequest to withdraw.

required

Returns:

Name Type Description
Dict Dict

The updated JoinRequest record (status "withdrawn").

Raises:

Type Description
HTTPError 403

Only the requester can withdraw.

HTTPError 409

Request is already closed.