RestrictionService

class RestrictionService[source]

Methods

create_entry_ticket

Create a short-lived entry ticket.

create_exam_environment_pass

Prepare to take an exam inside its exam environment.

create_exam_environment_session

Exchange an exam environment pass for a session.

put_allowed_ip

Add a single IP range to a restriction.

delete_allowed_ip

Remove a single IP range from a restriction.

get_all_entries

List all enrolled students with their entry counts and overrides.

enter

Activate a previously created entry ticket.

get_all_allowed_ips

Get all IP ranges for a restriction.

get

Get the settings for a restriction plus the caller's entry window.

patch

Update restriction settings.

patch_entry_override

Set or remove a per-student entry override for a restriction.

heartbeat

Send a heartbeat to keep an isolated exam session alive.
create_entry_ticket(json_body, *, restriction_id)[source]

Create a short-lived entry ticket.

Authenticates the caller via bearer token, validates the password (when set), and pre-checks the entry limit so a dead ticket isn’t issued. Writes an unused ticket to Redis and returns the ticket string.

Rejects when the calling token is itself an exam token for this course, since activating another ticket would kill the active session.

For a course running in an exam environment this must be called from inside the provider’s kiosk, which the student onboarded into before the entry window opened. The ticket returned is always direct: no entry ticket ever travels through the provider.

Parameters:
Returns:

A tagged response (EntryTicketResponse) carrying the ticket.

Return type:

EntryTicketResponse

create_exam_environment_pass(*, restriction_id)[source]

Prepare to take an exam inside its exam environment.

Mints a pass for the calling student, builds the entry point URL carrying it, provisions the student’s workspace at the provider, and returns the redirect that starts onboarding. The student is expected to still be in an ordinary browser here: this is the step that gets them into the kiosk.

Preparing is not entering. No password is checked, the entry window is not consulted, and no entry is consumed — a student prepares before the window opens and enters through PUT /entry_tickets/ once it does. Preparing again is always safe: it supersedes the previous pass and rewrites the same provider-side workspace.

The pass itself is never returned to the caller. It only ever travels in the fragment of the entry point URL embedded at the provider.

Parameters:
Returns:

The redirect that starts onboarding at the provider.

Return type:

RedirectPreparationResult

create_exam_environment_session(json_body, *, restriction_id)[source]

Exchange an exam environment pass for a session.

Called by the exam environment’s kiosk on its first load of the entry point. The pass is the credential and any Authorization header is ignored, mirroring how PUT /entries/ takes its ticket.

The kiosk signature is verified before the pass is looked at, so a caller outside the exam environment cannot probe pass tokens.

The session returned is a login and nothing more: course-scoped, not isolated, and granting no entry. A student who already entered the exam gets ISOLATED_SESSION_ACTIVE rather than having that session replaced.

Parameters:
Returns:

A login response containing the new access token.

Return type:

UserLoginResponse

put_allowed_ip(*, restriction_id, ip_range)[source]

Add a single IP range to a restriction.

Parameters:
Returns:

The added IP range.

Return type:

IPRange

delete_allowed_ip(*, restriction_id, ip_range)[source]

Remove a single IP range from a restriction.

Parameters:
Returns:

An empty response.

Return type:

None

get_all_entries(*, restriction_id, q='', page_size=50)[source]

List all enrolled students with their entry counts and overrides.

Parameters:

  • restriction_id (str) – The ID of the restriction.

  • q (str) – Only retrieve students whose name or username matches this value.

  • page_size (int) – The size of a single page, maximum is 100.

  • self (RestrictionService[AuthenticatedClient])

Returns:

A paginated list of entry overview entries per student.

Return type:

Response[EntryOverviewEntry]

enter(json_body, *, restriction_id)[source]

Activate a previously created entry ticket.

The ticket is the credential, the Authorization header is ignored, and a new session token is created while every previously issued token for the user is invalidated.

For a course running in an exam environment the activation must also carry a valid kiosk signature: the ticket says who the student is, the signature says where they are. Neither replaces the other, so the authentication of this route is unchanged.

Parameters:
Returns:

A login response containing the new access token.

Return type:

UserLoginResponse

get_all_allowed_ips(*, restriction_id, page_size=50)[source]

Get all IP ranges for a restriction.

Parameters:
Returns:

A paginated list of IP ranges.

Return type:

Response[IPRange]

get(*, restriction_id)[source]

Get the settings for a restriction plus the caller’s entry window.

Gated by course visibility (ensure_may_see), so any enrolled student can read it; the password it carries is viewer-relative. In addition to the serialized restriction it returns effective_entry_window: the requesting user’s override-resolved entry window.

Parameters:
Returns:

The restriction object plus the caller’s effective entry window.

Return type:

RestrictionWithEffectiveWindow

patch(json_body, *, restriction_id)[source]

Update restriction settings.

The request body mirrors the restriction JSON shape. All fields are optional; omitted fields are left unchanged.

proctoring attaches or detaches an exam environment provider. Attaching provisions the exam at the provider (and requires a configured entry window); detaching archives it at the provider while retaining its state, so re-attaching revives the same provider-side exam. Provider state is committed atomically with the rest of the patch: a provider failure fails the whole request.

Parameters:
Returns:

The updated restriction.

Return type:

Restriction

patch_entry_override(json_body, *, restriction_id, user_id)[source]

Set or remove a per-student entry override for a restriction.

The override row is removed entirely (the student falls back to the global session_lockdown settings) when the resolved limit and window are both null; any non-null field creates or updates the override.

Both fields follow the standard PATCH convention: omit one to leave the stored value unchanged, send null to clear it, or send a value to set it. override_entry_window carries both bounds together, so they are always set or cleared as a pair, and a set window must satisfy the same ordering and maximum-duration rules as the global window. A submitted window is ignored when the entry-window feature is disabled for the tenant, mirroring patch_restriction.

Parameters:
Returns:

The updated entry overview for this student.

Return type:

EntryOverviewEntry

heartbeat()[source]

Send a heartbeat to keep an isolated exam session alive.

When heartbeat enforcement is active, the session’s expires_at is set to a short window (5 minutes). This endpoint extends it forward, capped by max_expires_at.

For a course running in an exam environment the heartbeat must also carry a valid kiosk signature. On a rejected or uncheckable signature the session is not invalidated, but the refresh is skipped: a student who left the kiosk has their session lapse within one heartbeat cycle, while a transient provider blip self-heals on the next beat. The response tag says which happened.

If the session is already expired, the auth flow rejects the request before it reaches this endpoint (401).

Returns:

The tagged outcome with the session’s expires_at.

Parameters:

self (RestrictionService[AuthenticatedClient])

Return type:

RefreshedHeartbeatResponse | VerificationFailedHeartbeatResponse | VerificationUnavailableHeartbeatResponse