---
title: "Embedded Supervision Widget (Beta)"
slug: "embedded-supervision-widget-beta"
updated: 2025-08-19T16:17:56Z
published: 2025-09-24T19:36:55Z
canonical: "help.hyperscience.ai/embedded-supervision-widget-beta"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded Supervision Widget (Beta)

The Supervision widget enables you to embed our Supervision & QA tasks within a third-party workflow system. Thus, you no longer have to switch between Hyperscience and your existing workflow system to complete tasks.

Our Supervision widget supports the following types of tasks:

- Supervision:
  - Document Classification
  - Identification
  - Transcription
  - Flexible Extraction
  - Custom Supervision
- QA:
  - Document Classification
  - Identification
  - Transcription

> [!NOTE]
> **Not supported for SaaS instances**
> 
> The Supervision widget is available only for on-premise / private cloud instances of Hyperscience.

Note that the Supervision widget feature is in beta, and it is subject to change in future releases. If you’d like to embed a Supervision widget into your third-party system, contact your Hyperscience representative for more information.

The Supervision widget also supports Custom Supervision tasks. To learn more about Custom Supervision, see [Custom Supervision](/v42/docs/custom-supervision).

## Embedding a Supervision widget

You can embed a Supervision widget by following the below steps:

1. Get access to a Hyperscience instance.
2. Create a method for accessing our API tokens.
3. Import the Supervision widget into your third-party system.
4. Configure the widget.

### Step 1: Get access to a Hyperscience instance

To embed the Supervision widget into a third-party system, you need to get access to a Hyperscience instance installed on version 32+.

### Step 2: Create a method for accessing our API tokens

Users are authenticated in the widget, using their API token. To get the API token, we recommend querying the */profile/user//token* endpoint on your server. You can then forward the obtained API token to the frontend that implements the widget.

#### Step 2a: Set the *ALLOWED_ORIGINS* variable

Ask your system admin to do the following, and then restart and reinitialize the Hyperscience application:

In the “.env” file, set the *ALLOWED_ORIGINS* variable to include the domains of where you will embed the Supervision widget:

```plaintext
ALLOWED_ORIGINS=https://example.com
```

#### Step 2b: Create a superuser

To access the API token endpoint, you have to create a *superuser*. To create a superuser:

1. Run the following command.

```powershell
docker exec -it  
/var/www/venv/bin/python 
/var/www/forms/forms/manage.py createsuperuser
```

Note that you can run Docker commands on Podman with the *podman-docker* package. To learn how to install the *podman-docker* package, see step 2 in [Configuring Podman in RHEL 8](/deployment/docs/configuring-podman-in-rhel-8#configuring-podman).

2. Follow the on-screen instructions.

3. Open the Hyperscience application.

4. Go to **Users > Users**.

5. Click on the superuser’s username.

6. Copy the superuser’s authentication token.

We recommend adding the superuser’s username to the *TOKEN_REVALIDATION_EXEMPTED_USERS* variable in the “.env” file. Thus, you will avoid unexpected changes to the API token. To learn more, see [External Authentication Methods and API Users](/deployment/docs/external-authentication-methods-and-api-users).

#### Step 2c : Create a new endpoint to return the current user’s API token, if necessary

Depending on whether your server sends user data to your third-party system, you may need to create an endpoint that returns the user's token.

| **If...** | **Then...** |
| --- | --- |
| Your server sends user data to your third-party system. | You can add the users’ API tokens to the relevant entity in the third-party system. |
| Your server does not send user data to your third-party system. | You need to create a new endpoint that returns the user’s API token. |

Here is an example of how to create a new endpoint in the backend that returns the user’s API token:

```http
@app.route('/hyperscience/user-token', methods=['GET'])
def get_user_api_token():
    # get request user. Ex:
    username = request.user.username
    username = quote(username, safe='~()*!.\'')
    res = requests.get(
        f'https:///profile/user/{username}/token',
        headers = { 'Authorization': f'Bearer {SUPERUSER_API_TOKEN}'}
    )
    return res.text
```

### Step 3: Import the Supervision widget into your third-party system

Import the widget’s JavaScript and CSS to the frontend:

```javascript
<link rel="stylesheet" href="https://<HS Instance>/static/widget/main.css">
<script src="https://<HS Instance>/static/widget/main.js" type="text/javascript"></script>
```

Add a container for the widget. You must set the container’s *position* property to *relative*:

```css
<div id="hs-1" style="position:relative;"></div>
```

Initialize the widget in JavaScript:

```javascript
<script type="text/javascript">
  fetch('https://<Server>/hyperscience/user-token')
    .then(res => res.text())
    .then((apiToken) => {
      HyperscienceWidget.init('hs-1', {
        url: 'https://<HS Instance>,
        api_token: apiToken,
        <widget_options>
      });
    });
</script>
```

  

Note the following about the widget:

- The widget’s *min-width* property is 1000px.
- The widget’s *min-height* property is 700px.

### Step 4: Configure the widget

After importing the widget, *window.HyperscienceWidget* will become available. The following functions are available in *window.HyperscienceWidget*:

- *Purpose*
- *MessageType*
- *init*
- *destroy*

#### Purpose

*Purpose* is an enum of task purposes.

```java
enum Purpose {
  DOCUMENT_CLASSIFICATION = 'document_classification',
  IDENTIFICATION = 'identification',
  TRANSCRIPTION = 'transcription',
  FLEXIBLE_EXTRACTION = 'flexible_extraction',
  CUSTOM_SUPERVISION = 'custom_supervision',
  DOCUMENT_CLASSIFICATION_QA = 'document_classification_qa',
  IDENTIFICATION_QA = 'identification_qa',
  TRANSCRIPTION_QA = 'transcription_qa',
}
```

#### MessageType

*MessageType* is an enum of message types for the callback function.

```java
enum MessageType {
  ERROR = 'error',
  COMPLETE = 'complete',
}
```

#### init(id, options)

*init* is a function that initializes the widget to an HTML element. The parameters of the *init* function are the following:

- Element ID: string
- Options: object
  - url: string

URL of the Hyperscience instance
  - api_token: string

User’s API Token
  - callback: (message_type: MessageType, info: object) => void *(optional)*

The callback is currently called for two different events:
    - Errors - when the widget hits an error, the callback will be called with *message_type === MessageType.ERROR* and info will be an Error object.
    - Completed tasks - when all tasks are complete, the callback will be called with *message_type === MessageType.COMPLETE*, and *info* is an object with *Purpose* types as keys and the corresponding number of completed tasks as values.
  - One of the following parameters:
    - submission_id: string | number

To complete tasks for a given submission ID.
    - document_id: string | number

To complete tasks for a given document ID.
    - case_id: string | number

To complete tasks for a given case ID.
    - task_uuid: string

To complete a specific task.
    - purposes: Array

To complete tasks for specific task purposes.

You can find an example of the *init* function below:

```javascript
<script type="text/javascript">
  const hyperscienceCallback = (message_type, info) => {
    if (message_type === HyperscienceWidget.MessageType.ERROR) {
      console.error(info.message);
    } else if (message_type === HyperscienceWidget.MessageType.COMPLETE) {
      console.log('Tasks Completed', info);
      HyperscienceWidget.destroy('hs-1');
    }
  };
  HyperscienceWidget.init('hs-1', {
    url: 'https://<HS Instance>',
    api_token: '12345678910',
    submission_id: 10,
    callback: hyperscienceCallback,
  });
</script>
```

#### destroy(id)

*destroy* is a function that destroys the widget in an HTML element. The parameters of the *destroy* function are the following:

- HTML element ID

You can find an example of the *destroy* function below:

```javascript
<script type="text/javascript">
  HyperscienceWidget.destroy('hs-1');
</script>
```

## Additional notes

- Upon first login, the system automatically creates and assigns an API token to the user who is logging in. To be able to log in through the Supervision widget, a user needs to have logged in at least once to the main Hyperscience application. All subsequent logins can happen through the widget, using the user’s API token.