ProctorU JWT API Integration Guide

Overview

The ProctorU JWT (JSON Web Token) API provides enhanced security for online exams by ensuring that only authorized users can access exam URLs through ProctorU's proctoring system. This integration prevents students from bypassing proctoring by directly accessing exam links.

How JWT Security Works

JWT tokens provide a secure way to verify that exam access requests originate from ProctorU:

1. Key Exchange: A public key is shared between ProctorU and your institution during setup
2. Token Generation: When a student is redirected to an exam, ProctorU creates an encoded URL containing all necessary access information
3. Verification: Your institution uses the shared public key to decode and verify the request before granting exam access

Security Benefits

• Prevents unauthorized direct access to exam URLs
• Ensures all exam sessions are properly proctored
• Provides cryptographic verification of request authenticity
• Allows for secure communication between ProctorU and your institution

API Functions

Create JWT Parameters

Sets up JWT protection for all exam URLs at your institution.

Endpoint: POST /api/institutions/exam_url_parameters

Required Parameters:

• param_name: Must be set to "jwt"
• kind: Must be set to "QueryStringJsonWebToken"
• time_sent: Current timestamp in ISO 8601 format

Example Request:

curl --location --request POST \
'https://demo.proctoru.com/api/institutions/exam_url_parameters?param_name=jwt&kind=QueryStringJsonWebToken' \
--header 'Authorization-Token: <YOUR_API_KEY>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'time_sent=2020-05-12T21:15:14.840Z' \
--data-urlencode 'param_name=jwt' \
--data-urlencode 'kind=QueryStringJsonWebToken'

Response: The API returns a JSON object containing your institution's public key:

[{
  "created_at": "2020-05-14T21:47:49.453Z",
  "param_name": "jwt",
  "options": {
    "public_key": "-----BEGIN PUBLIC KEY-----\n[KEY_CONTENT]\n-----END PUBLIC KEY-----\n"
  }
}]

⚠️ Important: Save the public key from this response - you'll need it to verify JWT tokens.

List JWT Parameters

Retrieves current JWT configuration for your institution.

Endpoint: GET /api/institutions/exam_url_parameters

Example Request:

curl --location --request GET \
'https://demo.proctoru.com/api/institutions/exam_url_parameters' \
--header 'Authorization-Token: <YOUR_API_KEY>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'time_sent=2020-05-12T21:15:14.840Z'

Remove JWT Parameters

Disables JWT protection by removing the configuration from your institution.

Endpoint: DELETE /api/institutions/exam_url_parameters

Required Parameters:

• param_name: Set to "jwt"
• kind: Set to "QueryStringJsonWebToken"

Example Request:

curl --location --request DELETE \
'https://demo.proctoru.com/api/institutions/exam_url_parameters?param_name=jwt&kind=QueryStringJsonWebToken' \
--header 'Authorization-Token: <YOUR_API_KEY>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'time_sent=2020-05-13T14:33:27.978Z' \
--data-urlencode 'param_name=jwt' \
--data-urlencode 'kind=QueryStringJsonWebToken'

Implementation Guide

Step 1: Enable JWT Protection

1. Call the Create JWT API endpoint using your institution's API authorization token
2. Save the public key returned in the response
3. Implement JWT verification in your exam system

Step 2: JWT Verification Process

When receiving an exam access request:

1. Extract the JWT: Look for the jwt parameter in the URL query string
2. Decode the Token: Use your saved public key to decode the JWT
3. Verify Claims: Check that the token is valid and hasn't expired
4. Grant Access: Only allow access if the JWT verification succeeds

Step 3: Handle JWT Payload

A valid JWT will contain the following information:

{
  "aud": "Your Institution Name",
  "exp": 1612141400,
  "iat": 1612138774,
  "iss": "ProctorU",
  "jti": "unique-token-id",
  "nbf": 1612138774,
  "sub": "Exam_Name",
  "data": {
    "exam_url": "https://your-exam-system.com/exam/123"
  }
}

Token Claims Explained:

• aud (Audience): Your institution's name
• exp (Expiration): When the token expires (Unix timestamp)
• iat (Issued At): When the token was created (Unix timestamp)
• iss (Issuer): Always "ProctorU"
• jti (JWT ID): Unique identifier for this token
• nbf (Not Before): Token is not valid before this time
• sub (Subject): Name of the exam
• data: Contains the actual exam URL

Example Integration

Encrypted Exam URL Format

When ProctorU redirects a student to your exam, the URL will look like:

https://your-exam-system.com/exam?jwt=eyJhbGciOiJSUzUxMiJ9.eyJhdWQiOi...

Sample Verification Code (Pseudocode)

def verify_proctoru_jwt(jwt_token, public_key):
    try:
        # Decode and verify the JWT
        payload = jwt.decode(jwt_token, public_key, algorithms=['RS512'])
        
        # Verify issuer
        if payload.get('iss') != 'ProctorU':
            return False
            
        # Check if token is still valid
        current_time = time.time()
        if payload.get('exp', 0) < current_time:
            return False
            
        # Token is valid - extract exam URL
        exam_url = payload.get('data', {}).get('exam_url')
        return exam_url
        
    except jwt.InvalidTokenError:
        return False