RestrictionService¶
- class RestrictionService[source]¶
Methods
Create a short-lived entry ticket.
Add a single IP range to a restriction.
Remove a single IP range from a restriction.
List all enrolled students with their entry counts and overrides.
Activate a previously created entry ticket.
Get all IP ranges for a restriction.
Get the exam environment attachment options for a restriction.
Get a fresh deep link into the provider-hosted teacher UI.
Get the settings for a restriction plus the caller's entry window.
Update restriction settings.
Launch the exam environment for a non-direct entry ticket.
Set or remove a per-student entry override for a restriction.
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.
- Parameters:
json_body (
CreateEntryTicketRestrictionData) – The body of the request. SeeCreateEntryTicketRestrictionDatafor information about the possible fields. You can provide this data as aCreateEntryTicketRestrictionDataor as a dictionary.restriction_id (
str) – The id of the restriction.
- Returns:
A tagged response (EntryTicketResponse) carrying the ticket.
- Return type:
- put_allowed_ip(*, restriction_id, ip_range)[source]¶
Add a single IP range to a restriction.
- delete_allowed_ip(*, restriction_id, ip_range)[source]¶
Remove a single IP range from a restriction.
- get_all_entries(*, restriction_id, q='', page_size=50)[source]¶
List all enrolled students with their entry counts and overrides.
- Parameters:
- 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.
- Parameters:
json_body (
EnterRestrictionData) – The body of the request. SeeEnterRestrictionDatafor information about the possible fields. You can provide this data as aEnterRestrictionDataor as a dictionary.restriction_id (
str) – The ID of the restriction.
- Returns:
A login response containing the new access token.
- Return type:
- get_all_allowed_ips(*, restriction_id, page_size=50)[source]¶
Get all IP ranges for a restriction.
- get_exam_environment(*, restriction_id)[source]¶
Get the exam environment attachment options for a restriction.
Unlike the other exam environment routes this never fails on the release flag: with the feature off it reports no available providers, so clients drive their management UI off this list alone.
- Parameters:
restriction_id (
str) – The id of the restriction.
- Returns:
The providers the tenant can attach.
- Return type:
- get_exam_environment_teacher_ui(*, restriction_id, kind)[source]¶
Get a fresh deep link into the provider-hosted teacher UI.
kind selects the UI: settings is the provider’s exam-configuration widget, dashboard its live proctoring dashboard. Every call fetches a fresh single-use URL from the provider, so clients must request one per open and never store it.
- 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:
restriction_id (
str) – The id of the restriction.
- Returns:
The restriction object plus the caller’s effective entry window.
- Return type:
- 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:
json_body (
PatchRestrictionData) – The body of the request. SeePatchRestrictionDatafor information about the possible fields. You can provide this data as aPatchRestrictionDataor as a dictionary.restriction_id (
str) – The id of the restriction.
- Returns:
The updated restriction.
- Return type:
- launch_exam_environment(json_body, *, restriction_id)[source]¶
Launch the exam environment for a non-direct entry ticket.
Provisions this launch’s workspace at the provider — with the ticket embedded in its entry URL, so the kiosk can activate it from inside — and returns the redirect that sends the student into the kiosk. Nothing is stored: relaunching (e.g. after a kiosk crash) provisions afresh with a newly minted ticket.
The ticket must be an unactivated ticket for this restriction, created by the calling user. It is not consumed here; it is activated later through PUT /restrictions/<id>/entries/ from inside the kiosk.
- Parameters:
json_body (
LaunchExamEnvironmentRestrictionData) – The body of the request. SeeLaunchExamEnvironmentRestrictionDatafor information about the possible fields. You can provide this data as aLaunchExamEnvironmentRestrictionDataor as a dictionary.restriction_id (
str) – The id of the restriction to launch into.
- Returns:
The kiosk launch payload with the redirect to follow.
- Return type:
- 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:
json_body (
PatchEntryOverrideRestrictionData) – The body of the request. SeePatchEntryOverrideRestrictionDatafor information about the possible fields. You can provide this data as aPatchEntryOverrideRestrictionDataor as a dictionary.restriction_id (
str) – The ID of the restriction.user_id (
int) – The ID of the student.
- Returns:
The updated entry overview for this student.
- Return type:
- 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 restriction 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 — and the response tag tells the client to warn the student.
If the session is already expired, the auth flow rejects the request before it reaches this endpoint (401).
- Returns:
The tagged heartbeat outcome with the session’s expires_at.
- Parameters:
- Return type:
RefreshedHeartbeatResponse | VerificationFailedHeartbeatResponse | VerificationUnavailableHeartbeatResponse