Honorlock

https://docs.honorlock.com
Admin
Honorlock is an online proctoring platform that provides automated monitoring, identity...
Tokens:20,125
Snippets:181
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### isInitialized usage example

Source: https://docs.honorlock.com/integration-sdk

Example of checking if the SDK is initialized before performing actions.

```javascript
if(honorlock.isInitialized){
  //Do Something if the Honorlock SDK is initialized
}
```

--------------------------------

### authentication-started payload example

Source: https://docs.honorlock.com/webhooks

Example JSON payload for the authentication-started event, fired when a student begins authentication.

```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "authentication-started",
  "occurred_at": "2026-04-16T14:28:03+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```

--------------------------------

### setupSession() usage example

Source: https://docs.honorlock.com/integration-sdk

Example of passing session details and exam instructions to the Honorlock extension. This method should be called on the gate page that presents exam instructions and completes Honorlock Authentication steps.

```javascript
honorlock.setupSession({
  session: {
    //these values come from the api when creating the session
    session: {
      uuid: '5bcd03ff-4b7c-49f4-a3bc-a6c843c057cd',
      exam_taker_email: 'johndoe@myplatform.com',
      external_exam_id: '1c11c300-16e5-4e88-9b20-2ef658638a6a'
    },
    camera_url: 'https://app.honorlock.com/camera-url',
    configurations: {
      translations: tranlsations,
      exam_toggles: exam_toggles,
      shortcut_detection_enabled: shortcut_detection_enabled,
      simulated: boolean,
      guidelines: {
        allowed_messages: Array<string>
        not_allowed_messages: Array<string>
      },
      whitelisted_urls: Array<string>,
      additional_instructions: additional_instructions
    }
  },
  app_url: "https://myplatform.com",
  external_exam_id: '1c11c300-16e5-4e88-9b20-2ef658638a6a',
  exam_taker_id: '1c11c300-16e5-4e88-abfe-2ef658638a6a',
  exam_taker_name: 'John Doe',
  exam_taker_attempt_id: '3',
  //Optionally: Add an additional domain or URL that will be proctored during the test taking experience.
  additionally_supported_url: 'https://my-other-platform.com',
});
```

--------------------------------

### init() usage example

Source: https://docs.honorlock.com/integration-sdk

Example of calling init() with error handling. It waits for the extension to notify the SDK that content scripts are loaded; throws an exception if they fail to load after 10 seconds.

```javascript
try {
  await honorlock.init();
} catch (error) {
  //handle error
}
```

--------------------------------

### Install Honorlock Elements via npm

Source: https://docs.honorlock.com/elements

Install the @honorlock/elements package using npm. This is the recommended installation method.

```bash
npm install --save @honorlock/elements
```

--------------------------------

### Install SDK via npm

Source: https://docs.honorlock.com/integration-sdk

Install the Honorlock Integration SDK package using npm. Run this command in your project directory.

```bash
npm i --save @honorlock/integration-sdk-js
```

--------------------------------

### session-started payload example

Source: https://docs.honorlock.com/webhooks

Example JSON payload for the session-started event, fired when a student begins the proctored exam.

```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "session-started",
  "occurred_at": "2026-04-16T14:32:18+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```

--------------------------------

### pageHasExtensionInstallIframe() usage example

Source: https://docs.honorlock.com/integration-sdk

Example of using pageHasExtensionInstallIframe() to conditionally run platform-specific code, such as appending the install iframe to the page.

```javascript
if (honorlock.pageHasExtensionInstallIframe()) {
  // platform specific code
} else {
  // platform specific code
  //e.g append the install iframe to the page
}
```

--------------------------------

### resize() Usage Example

Source: https://docs.honorlock.com/elements

Example of calling window.HonorlockElements.resize() with an object specifying height and width of 500 pixels.

```javascript
window.HonorlockElements.resize(
  {
    height: 500,
    width: 500
  }
)
```

--------------------------------

### onBeginExam(callback) - Handle Start Exam click

Source: https://docs.honorlock.com/integration-sdk

Configures a callback with expected behavior after the test taker clicks the 'Start Exam' button after all auth steps are completed. Call on the gate page. The backend action should use the API to verify the test taker completed auth steps.

```javascript
honorlock.onBeginExam(() => {
  //platform specific code on how to proceed into the exam
  //e.g we submit a form on the page
  let gatewayForm = document.querySelector('[data-hl-gateway-form]');
  gatewayForm.submit();
});
```

--------------------------------

### authentication-completed payload example

Source: https://docs.honorlock.com/webhooks

Example JSON payload for the authentication-completed event, fired when a student finishes authentication.

```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "authentication-completed",
  "occurred_at": "2026-04-16T14:30:41+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```

--------------------------------

### authentication-started

Source: https://docs.honorlock.com/webhooks

Fires when a student begins authentication. Payload example shows the common envelope structure.

```APIDOC
## Event: authentication-started

### Description
Fires when a student begins authentication.

### Payload Example
```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "authentication-started",
  "occurred_at": "2026-04-16T14:28:03+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```
```

--------------------------------

### onBeginExam(callback)

Source: https://docs.honorlock.com/integration-sdk

Configures a callback with the expected behavior after the test taker clicks the 'Start Exam' button. Should be called on the gate page.

```APIDOC
## onBeginExam(callback)

### Description
Configures a callback with the expected behavior after the test taker clicks the 'Start Exam' button. Should be called on the gate page. The backend should verify auth steps via API.

### Method
onBeginExam(callback): void

### Parameters
- **callback** (function) - Required - A function to execute when the exam begins.

### Example
```javascript
honorlock.onBeginExam(() => {
  //platform specific code on how to proceed into the exam
  //e.g we submit a form on the page
  let gatewayForm = document.querySelector('[data-hl-gateway-form]');
  gatewayForm.submit();
});
```
```

--------------------------------

### session-created payload example

Source: https://docs.honorlock.com/webhooks

Example JSON payload for the session-created event, fired when a new exam session record is created for a student.

```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "session-created",
  "occurred_at": "2026-04-16T14:27:00+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```

--------------------------------

### Load Honorlock Elements via CDN

Source: https://docs.honorlock.com/elements

Alternative installation using a CDN. Not recommended for production use.

```html
<script type="module"
src="https://unpkg.com/@honorlock/elements"></script>
```

--------------------------------

### onExtensionVerified() usage example

Source: https://docs.honorlock.com/integration-sdk

Example of configuring a callback to allow the test taker to proceed after extension verification. This method should be called on the page where the extension verification iframe is configured.

```javascript
honorlock.onExtensionVerified(() => {
  //platform specific code to allow test taker to proceed.
  //e.g: Display a button that was previously hidden
  let continueButton = document.querySelector('[data-hl-extension-init]');
  continueButton.style.display = 'block';
});
```

--------------------------------

### session-started

Source: https://docs.honorlock.com/webhooks

Fires when a student begins the proctored exam. Payload example shows the common envelope structure.

```APIDOC
## Event: session-started

### Description
Fires when a student begins the proctored exam.

### Payload Example
```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "session-started",
  "occurred_at": "2026-04-16T14:32:18+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```
```

--------------------------------

### Verify in PHP

Source: https://docs.honorlock.com/webhooks

PHP example that reads the raw input, verifies the Signature header using HMAC-SHA256, and returns 401 on invalid signatures.

```APIDOC
## Verify in PHP

### Description
Verify the HMAC-SHA256 signature of an Honorlock webhook payload in PHP.

### Method
POST

### Endpoint
(any endpoint that receives the webhook)

### Headers
- **Signature** (string) - Required - HMAC-SHA256 of the raw JSON body, hex-encoded, keyed with your webhook secret.

### Request Body
- **raw JSON body** (string) - Required - The raw webhook payload. Must be read from `php://input` for signature verification.

### Request Example
```json
{
  "event_type": "example",
  "data": {}
}
```

### Response
#### Success Response (200)
- Empty body.

#### Error Response (401)
- Body: `invalid signature`

### Code Example
```php
$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, getenv('HONORLOCK_WEBHOOK_SECRET'));

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('invalid signature');
}

$payload = json_decode($raw, true);
// handle $payload['event_type'] ...
http_response_code(200);
```
```

--------------------------------

### authentication-completed

Source: https://docs.honorlock.com/webhooks

Fires when a student finishes authentication. Payload example shows the common envelope structure.

```APIDOC
## Event: authentication-completed

### Description
Fires when a student finishes authentication.

### Payload Example
```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "authentication-completed",
  "occurred_at": "2026-04-16T14:30:41+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```
```

--------------------------------

### Initialize Honorlock Elements with course context

Source: https://docs.honorlock.com/elements

Initialize the elements within your website's HTML documents. This example uses the default course context type.

```html
<script type="module" src="js/main.js"></script>

<script>
  document.addEventListener('HonorlockElements', () => {
    window.HonorlockElements.init({
      token: '<your-user-token>',
      debug: true,
      context: {
        type: 'course',
        id: '<course-uuid>',
      },
    });
  });
</script>
```

--------------------------------

### examLoaded()

Source: https://docs.honorlock.com/integration-sdk

Notifies the Honorlock Extension that an exam has been loaded. Should be called once the exam has started and questions are visible.

```APIDOC
## examLoaded()

### Description
Notifies the Honorlock Extension that an exam has been loaded. Should be called once the exam has started and the test taker is on the page where exam questions are visible.

### Method
examLoaded(): void

### Parameters
None

### Example
```javascript
honorlock.examLoaded();
```
```

--------------------------------

### Rate Limit Response Headers Example

Source: https://docs.honorlock.com/api

Shows the response headers returned by the API indicating the rate limit and remaining requests in the current one-minute window.

```http
X-Ratelimit-Limit: 300
X-Ratelimit-Remaining: 100

```

--------------------------------

### pageHasExtensionInstallIframe()

Source: https://docs.honorlock.com/integration-sdk

Utility method to determine if the Extension Install iFrame is present on the current page. Can be used anywhere as required.

```APIDOC
## pageHasExtensionInstallIframe()

### Description
Utility method to determine if the Extension Install iFrame is present on the current page. Can be used anywhere as required.

### Signature
```
pageHasExtensionInstallIframe(): boolean
```

### Example
```
if (honorlock.pageHasExtensionInstallIframe()) {
  // platform specific code
} else {
  // platform specific code
  //e.g append the install iframe to the page
}
```

```

--------------------------------

### onExtensionOffline(callback)

Source: https://docs.honorlock.com/integration-sdk

Allows the platform to execute logic when the Honorlock Extension is unavailable. Should be called once the exam has started.

```APIDOC
## onExtensionOffline(callback)

### Description
Allows the platform to execute logic when the Honorlock Extension is unavailable. Should be called once the exam has started and questions are visible.

### Method
onExtensionOffline(callback): void

### Parameters
- **callback** (function) - Required - A function to execute when the extension is offline.

### Example
```javascript
honorlock.onExtensionOffline(() => {
  //platform specific code on how to proceed when the extension is offline.
  //e.g we navigate back to the exam extension check page
  window.location = "/exams/$exam->id";
});
```
```

--------------------------------

### onExamLoaded(callback)

Source: https://docs.honorlock.com/integration-sdk

Registers a callback that is triggered when an exam is loaded. Should be called once the exam has started and questions are visible.

```APIDOC
## onExamLoaded(callback)

### Description
Registers a callback that is triggered when an exam is loaded. Should be called once the exam has started and the test taker is on the page where exam questions are visible.

### Method
onExamLoaded(callback): void

### Parameters
- **callback** (function) - Required - A function to execute when the exam is loaded.

### Example
```javascript
honorlock.onExamLoaded(() => {
  //platform specific code on how to proceed when loading the exam
  console.log('exam loaded');
});
```
```

--------------------------------

### onExtensionVerified(callback)

Source: https://docs.honorlock.com/integration-sdk

Configures a callback to be executed after the Honorlock extension installation has been confirmed. Should be called on the page where the extension verification iFrame is configured.

```APIDOC
## onExtensionVerified(callback)

### Description
Configures a callback to be executed after the Honorlock extension installation has been confirmed. Should be called on the page where the extension verification iFrame is configured.

### Signature
```
onExtensionVerified(callback): void
```

### Parameters
- **callback** (function) - Required - The callback to execute when the extension is verified.

### Example
```
honorlock.onExtensionVerified(() => {
  //platform specific code to allow test taker to proceed.
  //e.g: Display a button that was previously hidden
  let continueButton = document.querySelector('[data-hl-extension-init]');
  continueButton.style.display = 'block';
});
```

```

--------------------------------

### session-created

Source: https://docs.honorlock.com/webhooks

Fires when a new exam session record is created for a student. Payload example shows the common envelope structure.

```APIDOC
## Event: session-created

### Description
Fires when a new exam session record is created for a student.

### Payload Example
```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "session-created",
  "occurred_at": "2026-04-16T14:27:00+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```
```

--------------------------------

### Get access token and verify with curl

Source: https://docs.honorlock.com/

Exchange API client credentials for a short-lived access token, then verify access by calling the /me endpoint. Replace client_id and client_secret with your actual credentials.

```bash
# 1. Get a token
curl -X POST https://app.honorlock.com/api/en/v1/token \
  -d '{"client_id":"...","client_secret":"..."}'

# 2. Verify your access
curl https://app.honorlock.com/api/en/v1/me \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Download URL

Source: https://docs.honorlock.com/data-downloads

Retrieves a presigned URL to the generated file for a subscription. The URL is valid for 1 hour and streams the file directly from object storage.

```APIDOC
## Get Download URL

### Description
Retrieves a presigned URL to the generated file for a subscription. The URL is valid for 1 hour and streams the file directly from object storage.

### Method
GET

### Endpoint
(Not specified in source)

### Parameters
#### Path Parameters
- **slug** (string) - Required - The subscription's slug.

### Response
#### Success Response (200)
- **data.download_url** (string) - The presigned URL to the file.
- **data.expires_at** (string) - The expiration timestamp of the URL.

#### Response Example
```
{
  "data": {
    "download_url": "https://s3.amazonaws.com/.../sessions-by-date.csv?X-Amz-Signature=...",
    "expires_at": "2026-04-16T15:32:00.000000Z"
  }
}
```

### Error Handling
- Returns `404` if the file has not been generated yet.
- Returns `403 Forbidden` if organization does not have access.
```

--------------------------------

### Verify in Node (Express)

Source: https://docs.honorlock.com/webhooks

Express middleware example that captures the raw body, verifies the Signature header using HMAC-SHA256, and returns 401 on invalid signatures.

```APIDOC
## Verify in Node (Express)

### Description
Verify the HMAC-SHA256 signature of an Honorlock webhook payload in a Node.js Express application.

### Method
POST

### Endpoint
/honorlock-webhook

### Headers
- **Signature** (string) - Required - HMAC-SHA256 of the raw JSON body, hex-encoded, keyed with your webhook secret.

### Request Body
- **raw JSON body** (object) - Required - The raw webhook payload. Must be captured as raw bytes for signature verification.

### Request Example
```json
{
  "event_type": "example",
  "data": {}
}
```

### Response
#### Success Response (200)
- Empty body.

#### Error Response (401)
- Body: `invalid signature`

### Code Example
```javascript
import crypto from 'crypto'
import express from 'express'

const app = express()

// Capture the raw body for signature verification.
app.use(express.raw({ type: 'application/json' }))

app.post('/honorlock-webhook', (req, res) => {
  const signature = req.header('Signature')
  const expected = crypto
    .createHmac('sha256', process.env.HONORLOCK_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')

  const ok =
    signature &&
    crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    )

  if (!ok) return res.status(401).send('invalid signature')

  const payload = JSON.parse(req.body.toString('utf8'))
  // handle payload.event_type ...
  res.status(200).end()
})
```
```

--------------------------------

### Generate Access Token - 200 Response

Source: https://docs.honorlock.com/api

Example JSON response for a successful token generation request, containing the bearer token and expiration details.

```json
{
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI...",
    "expires_in": 86400,
    "created_at": "2023-03-12T17:30:00.000000Z",
    "expires_at": "2023-03-12T18:30:00.000000Z"
  }
}

```

--------------------------------

### onExtensionRemoved(callback)

Source: https://docs.honorlock.com/integration-sdk

Allows the platform to execute logic when the test taker removes/uninstalls the Honorlock Extension. Should be called once the exam has started.

```APIDOC
## onExtensionRemoved(callback)

### Description
Allows the platform to execute logic when the test taker removes/uninstalls the Honorlock Extension. Should be called once the exam has started and questions are visible.

### Method
onExtensionRemoved(callback): void

### Parameters
- **callback** (function) - Required - A function to execute when the extension is removed.

### Example
```javascript
honorlock.onExtensionRemoved(() => {
  //platform specific code on how to proceed when the extension has been removed.
  //e.g we navigate back to the exam extension check page
  window.location = "/exams/$exam->id";
});
```
```

--------------------------------

### pageHasExtensionInstallIframe() signature

Source: https://docs.honorlock.com/integration-sdk

Signature of the pageHasExtensionInstallIframe() method, which returns a boolean indicating if the Extension Install iFrame is present on the current page.

```typescript
pageHasExtensionInstallIframe(): boolean
```

--------------------------------

### onExamSubmit() Example: Register Callback

Source: https://docs.honorlock.com/integration-sdk

Registers a callback with honorlock.onExamSubmit that submits a form with the data-hl-exam-form attribute. The callback should contain platform-specific post-exam submission logic.

```javascript
honorlock.onExamSubmit(() => {
  //platform specific code on how to proceed when submitting the exam
  //e.g we submit a form on the page
  let examForm = document.querySelector('[data-hl-exam-form]');
  examForm.submit();
});
```

--------------------------------

### onExtensionOffline(callback) - Handle extension offline

Source: https://docs.honorlock.com/integration-sdk

Executes logic when the Honorlock Extension is unavailable. Call once the exam has started and the test taker is on the page where exam questions are visible.

```javascript
honorlock.onExtensionOffline(() => {
  //platform specific code on how to proceed when the extension is offline.
  //e.g we navigate back to the exam extension check page
  window.location = "/exams/$exam->id";
});
```

--------------------------------

### questionLoaded(question_number, question_text, question_html) - Send question info

Source: https://docs.honorlock.com/integration-sdk

Sends information about the active question. Call once the exam has started and the test taker is on the page where exam questions are visible. For multiple questions per page, call when the test taker focuses the question or any of its answers.

```javascript
const currentQuestionIdentifier = document.querySelector('#questionWrapper.identifier');
const currentQuestion = document.querySelector('#questionWrapper .text');

honorlock.questionLoaded(
  currentQuestionIdentifier.textContent,
  currentQuestion.textContent
  currentQuestion.innerHTML,
);
```

--------------------------------

### init()

Source: https://docs.honorlock.com/integration-sdk

Initializes the SDK by communicating with the Honorlock extension. Must be called before any other SDK methods. Works asynchronously and throws an exception if content scripts fail to load after 10 seconds.

```APIDOC
## init()

### Description
Initializes the SDK by communicating with the Honorlock extension. Must be called before any other SDK methods. Works asynchronously and throws an exception if content scripts fail to load after 10 seconds.

### Method
init()

### Signature
```
init()
```

### Example
```
try {
  await honorlock.init();
} catch (error) {
  //handle error
}
```

```

--------------------------------

### Load SDK via CDN

Source: https://docs.honorlock.com/integration-sdk

Alternative way to load the SDK using a CDN. Not recommended for production.

```html
<script type="module"
src="https://unpkg.com/@honorlock/integration-sdk-js?module"></script>
```

--------------------------------

### setupSession() signature

Source: https://docs.honorlock.com/integration-sdk

Signature of the setupSession() method, which accepts a session configuration object.

```typescript
setupSession(sessionConfig): void
```

--------------------------------

### setupSession(sessionConfig)

Source: https://docs.honorlock.com/integration-sdk

Passes details about the session and exam instructions to the Honorlock extension. Should be called on the gate page that presents exam instructions and completes Honorlock Authentication steps.

```APIDOC
## setupSession(sessionConfig)

### Description
Passes details about the session and exam instructions to the Honorlock extension. Should be called on the gate page that presents exam instructions and completes Honorlock Authentication steps.

### Signature
```
setupSession(sessionConfig): void
```

### Parameters
- **sessionConfig** (object) - Required - Configuration object containing session details.
  - **session** (object) - Required - Session details.
    - **session** (object) - Required - Session identifiers.
      - **uuid** (string) - Required - Session UUID.
      - **exam_taker_email** (string) - Required - Email of the exam taker.
      - **external_exam_id** (string) - Required - External exam ID.
    - **camera_url** (string) - Required - Camera URL.
    - **configurations** (object) - Required - Configuration settings.
      - **translations** (object) - Required - Translation settings.
      - **exam_toggles** (object) - Required - Exam toggle settings.
      - **shortcut_detection_enabled** (boolean) - Required - Whether shortcut detection is enabled.
      - **simulated** (boolean) - Required - Whether the session is simulated.
      - **guidelines** (object) - Required - Guidelines settings.
        - **allowed_messages** (Array<string>) - Required - Allowed messages.
        - **not_allowed_messages** (Array<string>) - Required - Not allowed messages.
      - **whitelisted_urls** (Array<string>) - Required - Whitelisted URLs.
      - **additional_instructions** (string) - Required - Additional instructions.
  - **app_url** (string) - Required - The platform's app URL.
  - **external_exam_id** (string) - Required - External exam ID.
  - **exam_taker_id** (string) - Required - Exam taker ID.
  - **exam_taker_name** (string) - Required - Exam taker name.
  - **exam_taker_attempt_id** (string) - Required - Exam taker attempt ID.
  - **additionally_supported_url** (string) - Optional - Additional domain or URL to be proctored.

### Example
```
honorlock.setupSession({
  session: {
    //these values come from the api when creating the session
    session: {
      uuid: '5bcd03ff-4b7c-49f4-a3bc-a6c843c057cd',
      exam_taker_email: 'johndoe@myplatform.com',
      external_exam_id: '1c11c300-16e5-4e88-9b20-2ef658638a6a'
    },
    camera_url: 'https://app.honorlock.com/camera-url',
    configurations: {
      translations: tranlsations,
      exam_toggles: exam_toggles,
      shortcut_detection_enabled: shortcut_detection_enabled,
      simulated: boolean,
      guidelines: {
        allowed_messages: Array<string>,
        not_allowed_messages: Array<string>
      },
      whitelisted_urls: Array<string>,
      additional_instructions: additional_instructions
    }
  },
  app_url: "https://myplatform.com",
  external_exam_id: '1c11c300-16e5-4e88-9b20-2ef658638a6a',
  exam_taker_id: '1c11c300-16e5-4e88-abfe-2ef658638a6a',
  exam_taker_name: 'John Doe',
  exam_taker_attempt_id: '3',
  //Optionally: Add an additional domain or URL that will be proctored during the test taking experience.
  additionally_supported_url: 'https://my-other-platform.com',
});
```

```

--------------------------------

### support-interaction-ended

Source: https://docs.honorlock.com/webhooks

Event sent when a support interaction ends. The payload structure is identical to the started event.

```APIDOC
## support-interaction-ended

### Description
Support interaction ends.

### Event Type
`support-interaction-ended`

### Payload Example
```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "support-interaction-ended",
  "occurred_at": "2026-04-16T14:28:03+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```

### Fields
- **id** (string) - Unique identifier for the event.
- **event_type** (string) - The type of event, always `support-interaction-ended`.
- **occurred_at** (string) - ISO 8601 timestamp of when the event occurred.
- **session** (object) - Contains session details: `uuid`, `exam_taker_name`, `exam_taker_email`, `metadata`.
- **organization** (object) - Contains organization details: `uuid`, `name`.
- **external** (object) - Contains external identifiers: `exam_taker_id`, `course_id`, `exam_id`, `attempt_id`.
```

--------------------------------

### onExtensionVerified() signature

Source: https://docs.honorlock.com/integration-sdk

Signature of the onExtensionVerified() method, which accepts a callback to be executed after the extension installation is confirmed.

```typescript
onExtensionVerified(callback): void
```

--------------------------------

### Initialize Honorlock Elements with search_and_destroy context

Source: https://docs.honorlock.com/elements

Change context type to 'search_and_destroy' and include an exam uuid to immediately open the Search and Destroy page for an exam.

```html
<script type="module" src="js/main.js"></script>

<script>
  document.addEventListener('HonorlockElements', () => {
    window.HonorlockElements.init({
      token: '<your-user-token>',
      debug: true,
      context: {
        type: 'search_and_destroy'
        id: '<exam_uuid>',
      },
    });
  });
</script>
```

--------------------------------

### onLaunchProctoringIframeResize(callback)

Source: https://docs.honorlock.com/integration-sdk

Configures a callback to adjust the height of the exam instructions iframe as content changes. Should be called on the gate page.

```APIDOC
## onLaunchProctoringIframeResize(callback)

### Description
Configures a callback to adjust the height of the exam instructions iframe as content changes. Should be called on the gate page that presents exam instructions and authentication steps.

### Method
onLaunchProctoringIframeResize(callback): void

### Parameters
- **callback** (function) - Required - A function that receives data with the updated iframe height.

### Example
```javascript
honorlock.onLaunchProctoringIframeResize((data) => {
  let updatedIframeHeight = data.launch_proctoring_data.iframe_height;
  //platform specific code on how to get the iframe and adjust the height.
  let iframe = document.getElementById('launch-proctoring-iframe');
  iframe.style.height = updatedIframeHeight + 'px';
});
```
```

--------------------------------

### Initialize Honorlock Elements with exam_settings context

Source: https://docs.honorlock.com/elements

Change context type to 'exam_settings' and include an exam uuid to immediately open a particular exam's settings page.

```html
<script type="module" src="js/main.js"></script>

<script>
  document.addEventListener('HonorlockElements', () => {
    window.HonorlockElements.init({
      token: '<your-user-token>',
      debug: true,
      context: {
        type: 'exam_settings'
        id: '<exam_uuid>',
      },
    });
  });
</script>
```

--------------------------------

### examClosed() Example: Exit Exam Button

Source: https://docs.honorlock.com/integration-sdk

Attaches a click listener to an element with the data-hl-exit-exam attribute, calling honorlock.examClosed() when clicked.

```javascript
const exitExamButton = document.querySelector('[data-hl-exit-exam]');

exitExamButton.addEventListener('click', (event) => {
  honorlock.examClosed();
});
```

--------------------------------

### Initialize Honorlock Elements with session context

Source: https://docs.honorlock.com/elements

Change context type to 'session' and include a student session uuid to immediately open a particular student session.

```html
<script type="module" src="js/main.js"></script>

<script>
  document.addEventListener('HonorlockElements', () => {
    window.HonorlockElements.init({
      token: '<your-user-token>',
      debug: true,
      context: {
        type: 'session'
        id: '<student_session_uuid>',
      },
    });
  });
</script>
```

--------------------------------

### init() signature

Source: https://docs.honorlock.com/integration-sdk

Signature of the init() method. It communicates with the Honorlock extension and must be called before any other SDK methods.

```javascript
init()
```

--------------------------------

### Import Honorlock Elements library

Source: https://docs.honorlock.com/elements

Add the components library to your website's JavaScript file that runs on all pages where the widget elements will be utilized.

```javascript
import '@honorlock/elements';
```

--------------------------------

### Create Subscription

Source: https://docs.honorlock.com/data-downloads

Creates a subscription binding a download type to an output format for your organization. The (organization, download_type) pair is unique.

```APIDOC
## Create Subscription

### Description
Creates a subscription binding a download type to an output format for your organization. The (organization, download_type) pair is unique.

### Method
POST

### Endpoint
(Not specified in source)

### Parameters
#### Request Body
- **download_type** (string) - Required - The slug of the download type.
- **format** (string) - Required - The output format (e.g., `csv`).

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
- **data** (object) - Subscription details.

#### Response Example
(Not provided in source)

### Error Handling
- Returns `403 Forbidden` if organization does not have access.
```

--------------------------------

### Access global Honorlock instance

Source: https://docs.honorlock.com/integration-sdk

After importing the SDK, the instance can be accessed via globalThis.Honorlock or window.Honorlock.

```javascript
globalThis.Honorlock
// OR
window.Honorlock
```

--------------------------------

### Initialize Honorlock Elements with exam_results context

Source: https://docs.honorlock.com/elements

Change context type to 'exam_results' and include an exam uuid to immediately open a particular exam's results page.

```html
<script type="module" src="js/main.js"></script>

<script>
  document.addEventListener('HonorlockElements', () => {
    window.HonorlockElements.init({
      token: '<your-user-token>',
      debug: true,
      context: {
        type: 'exam_results'
        id: '<exam_uuid>',
      },
    });
  });
</script>
```

--------------------------------

### Initialize Honorlock Elements with custom width and height

Source: https://docs.honorlock.com/elements

Specify a specific width and height for the widget as required within your application.

```html
<script type="module" src="js/main.js"></script>

<script>
  document.addEventListener('HonorlockElements', () => {
    window.HonorlockElements.init({
      token: '<your-user-token>',
      context: {
        type: 'course'
        id: '<course-uuid>',
      },
      width: 500,
      height: 500,
      debug: true,
    });
  });
</script>
```

--------------------------------

### examLoaded() - Notify extension exam loaded

Source: https://docs.honorlock.com/integration-sdk

Notifies the Honorlock Extension that an exam has been loaded. Call once the exam has started and the test taker is on the page where exam questions are visible.

```javascript
honorlock.examLoaded();
```

--------------------------------

### support-interaction-started

Source: https://docs.honorlock.com/webhooks

Event sent when a student begins an interaction with Honorlock support. The payload includes session, organization, and external identifiers.

```APIDOC
## support-interaction-started

### Description
Student begins an interaction with Honorlock support.

### Event Type
`support-interaction-started`

### Payload Example
```json
{
  "id": "2981b1a7-7e6f-4a58-971f-45010df72dec",
  "event_type": "support-interaction-started",
  "occurred_at": "2026-04-16T14:28:03+00:00",
  "session": {
    "uuid": "8a7f1c3e-0b5d-4a1e-9c7d-2e1f8b4a6c9d",
    "exam_taker_name": "Jane Doe",
    "exam_taker_email": "jane.doe@example.edu",
    "metadata": null
  },
  "organization": {
    "uuid": "0eac5b21-9e4a-4f5b-a3f8-7c9d1e2f3a4b",
    "name": "Acme University"
  },
  "external": {
    "exam_taker_id": "student-12345",
    "course_id": "COURSE-789",
    "exam_id": "EXAM-42",
    "attempt_id": "ATTEMPT-1"
  }
}
```

### Fields
- **id** (string) - Unique identifier for the event.
- **event_type** (string) - The type of event, always `support-interaction-started`.
- **occurred_at** (string) - ISO 8601 timestamp of when the event occurred.
- **session** (object) - Contains session details: `uuid`, `exam_taker_name`, `exam_taker_email`, `metadata`.
- **organization** (object) - Contains organization details: `uuid`, `name`.
- **external** (object) - Contains external identifiers: `exam_taker_id`, `course_id`, `exam_id`, `attempt_id`.
```

--------------------------------

### isInitialized

Source: https://docs.honorlock.com/integration-sdk

Property that indicates whether the SDK has been initialized. Useful for conditional logic.

```APIDOC
## isInitialized

### Description
Property that indicates whether the SDK has been initialized. Useful for conditional logic.

### Signature
```
isInitialized: boolean
```

### Example
```
if(honorlock.isInitialized){
  //Do Something if the Honorlock SDK is initialized
}
```

```

--------------------------------

### onExamLoaded(callback) - Register exam loaded callback

Source: https://docs.honorlock.com/integration-sdk

Registers a callback triggered when an exam is loaded. Call once the exam has started and the test taker is on the page where exam questions are visible.

```javascript
honorlock.onExamLoaded(() => {
  //platform specific code on how to proceed when loading the exam
  console.log('exam loaded');
});
```

--------------------------------

### Manually instantiate Honorlock

Source: https://docs.honorlock.com/integration-sdk

Create a new Honorlock instance manually.

```javascript
import Honorlock from '@honorlock/integration-sdk-js';

const honorlock = new Honorlock();
```
Tokens:
Raw