Adding Proctoring to a Custom Assessment Platform

What does a custom platform actually have to add?

A purpose-built assessment platform already owns the hard parts: a user model, an exam or item bank, an attempt state machine, timing, and grading. Proctoring does not replace any of that. It attaches to the moments you already have, when an attempt starts, while it runs, and when it ends, and hands you back a server-side integrity verdict to fold into results. The integration is small on purpose, so the risk stays contained to three calls rather than spreading through your codebase.

This is the same three-part split described in How to add proctoring to a web application, viewed from the angle of a platform with its own domain model. If you are still deciding between the SDK, the REST API, and a drop-in LMS plugin, start with Proctoring SDK vs API vs LMS plugin. To set expectations for what a browser can and cannot see before you design your review rules, read what browser-based proctoring can and cannot detect.

Step 2: Mint the session where an attempt starts

Hook the mint into the moment your platform already creates an attempt. Because it carries your access-token and secret-token, minting stays on your backend, never in the exam page. Store the returned session_id on the attempt row, keyed exactly like everything else you persist, and hand only session_jwt and session_id to the browser.

// Your backend, when a candidate starts an attempt.
// access-token and secret-token never leave the server.
POST /v1/sessions
access-token: <YOUR_ACCESS_TOKEN>
secret-token: <YOUR_SECRET_TOKEN>
content-type: application/json

{
  "external_user_id": "your-user-pk",      // your users table PK, not an email
  "exam_id": "your-exam-pk",               // your exam/quiz identifier
  "attempt_id": "your-attempt-pk",         // your attempt record PK — enables resume
  "allowed_origins": ["https://exams.yourcompany.com"],
  "reference_image_base64": "data:image/jpeg;base64,/9j/4AAQ...",  // optional: a photo you already hold
  "ttl_seconds": 7200                      // exam length plus a buffer
}

// Response — persist session_id on the attempt, pass the rest to the browser
{
  "session_id": "6a7b18df70e4f8ecf2597b6f",
  "session_jwt": "eyJhbGciOi...",
  "expires_at": 1786443201
}

If your onboarding already captured a known-good photo of the candidate, reuse it: pass it as reference_image_base64 (bare base64 or a data: URI, JPEG, PNG, or WebP up to 1 MB decoded). It is stored at mint, so a bad payload fails fast with a 400, and because you send the bytes, nothing of yours needs to be publicly reachable. Set ttl_seconds to your exam length plus a buffer and read the returned expires_at, since values outside the allowed range are clamped rather than rejected.

Step 4: Read the verdict when analysis is complete

After the attempt, your backend calls GET /v1/sessions/:id with the session_id you stored. Face analysis is deferred, not real-time, so fetch the report once status is validated, or equivalently when integrity.analysis_complete is true. Before that, face counts are zero and identity_match is pending, which is an unfinished result rather than a clean one. Poll on a sensible interval such as every 30 seconds with backoff, or fetch on demand when a reviewer opens the attempt.

// Your backend, once status is "validated"
// (or integrity.analysis_complete is true).
GET /v1/sessions/6a7b18df70e4f8ecf2597b6f
access-token: <YOUR_ACCESS_TOKEN>
secret-token: <YOUR_SECRET_TOKEN>

// Response (trimmed) — store this against your attempt
{
  "status": "validated",
  "integrity": {
    "score": 100,
    "level": "low",
    "flagged": false,
    "identity_match": "pass",
    "reasons": []
  }
}

The integrity.score starts at 100 and drops as penalties apply. The level is low at 80 or above, medium from 50 to 79, and high below 50, and flagged turns true below 80. The verdict is computed server-side only, so a candidate cannot influence it from your exam page no matter what they do in the browser.

Common mistakes integrating a custom platform

• Generating attempt_id per page load. A random value created when the exam screen opens defeats resume, so every refresh mints a new session and bills the attempt twice. Fix: derive attempt_id from your own attempt record so it is stable for the whole attempt.
• Minting from the browser. Putting access-token and secret-token in client code hands anyone the ability to mint sessions billed to you and read your reports. Fix: mint only on your backend and pass the browser just session_jwt and session_id.
• Reading the report the instant the exam ends. Before status is validated, face counts are zero and identity_match is pending. Treating that as a clean pass hides real findings. Fix: gate your results pipeline on validated and poll with backoff.
• Auto-failing on the score. The score is a triage signal, not a verdict on the person. Fix: route flagged attempts to a reviewer with reasons and evidence, and let a human make the call.
• Skipping allowed_origins and ttl_seconds. Without allowed_origins any page can run the session; without a sensible ttl_seconds the token can die mid-exam. Fix: pin the origins your exam runs on and set the token lifetime to your exam length plus a buffer, with token-expired as the safety net.

Frequently Asked Questions

Next steps

Ready to proctor exams in your own platform? Sign up at app.proctorlink.com to get your API keys, wire the three calls above into a real attempt, and check the reviewer workload before you commit.

More Proctoring Guides