External access to the Transcript Editor

Introduction

In the following sections, you will find information about the integration of the Transcript Editor into your workflow or third-party application.

You can generate a URL to let your users access the Transcript Editor without the need to log in to the DeepVA platform. This enables certain use cases where you want to provide a seamless integration of the Transcript Editor into your application.

The Transcript Editor can be embedded into your web-based application or accessed via a direct link (deep linking).

Authentication

You can authorize users to access the Transcript Editor by generating a JWT token with the necessary scopes. The JWT token is used to authenticate the user and to grant access to the Transcript Editor.

A secret is required to encode the JWT token. The secret is part of the Access Key that you can create via the DeepVA API. Never share the secret with someone.

You have to generate an Access Key with the following scopes:

• transcript.read
• transcript.write
• export.read
• export.write

Here is an example to encode a JWT token based on the secret of an Access Key

Python

import jwt
secret = "PUT YOUR SECRET FROM YOUR ACCESS KEY HERE"
jwt_token = jwt.encode({"exp": 1723291200}, secret, algorithm='HS256')
print(jwt_token)

The JWT token is provided as a query parameter in the URL to access the Transcript Editor.

Important: The exp claim of the JWT token is mandatory! See section Token expiration.

Accessing the Transcript Editor

Use the following URL to access the Transcript Editor:

https://api.deepva.com/transcript-editor?transcript_id=<TRANSCRIPT_ID>&token=<ACCESS_KEY.KEY>.<JWT_TOKEN>

The token is a combination of the access key public key field and the JWT token. The access key is the key of the Access Key and the JWT token is the encoded token based on the secret of the Access Key.

Replace <TRANSCRIPT_ID> with the ID of the transcript you want to edit. The <TRANSCRIPT_ID> can be obtained by the Transcript resource.

An optional query parameter video_source can be added to the URL to override the video source for the transcript.

https://api.deepva.com/transcript-editor?transcript_id=<TRANSCRIPT_ID>&video_source=<PUBLIC_URL_TO_VIDEO>&token=<ACCESS_KEY.KEY>.<JWT_TOKEN>

Token expiration

To ensure that access to the Transcript Editor is time-limited, you must include the exp (expiration) claim in the payload of the JWT token. This claim defines the exact time when the token will expire and can no longer be used to access the Transcript Editor. The exp claim is specified as a Unix timestamp (i.e., the number of seconds since January 1, 1970).

Also see the JTW standard as described here.

Here is an example to encode a JWT token based on the secret of an Access Key including the expiration date.

Python

import jwt
secret = "PUT YOUR SECRET FROM YOUR ACCESS KEY HERE"
jwt_token = jwt.encode({"exp": 1723291200}, secret, algorithm="HS256")
print(jwt_token)

The token above will expire on the 10.08.2024 at 2 pm (unix timestamp: 1723291200).

Restrict access to a specific transcript

To restrict a JWT token's access to a specific transcript by its ID, you can include a custom claim in the token's payload.

This restriction is implemented using a permissions field, as shown below:

{
    "exp": 1723291200,
    "permissions": {
        "transcript_id": "929aee69-e5e3-4e08-9684-33b3f36e529d"
    }
}

In this example, the token is limited to accessing only the transcript with the ID 929aee69-e5e3-4e08-9684-33b3f36e529d. Any attempt to access other transcripts using this token will be denied.

Python

import jwt
secret = "PUT YOUR SECRET FROM YOUR ACCESS KEY HERE"
jwt_token = jwt.encode({
    "exp": 1723291200,
    "permissions": {
        "transcript_id": "929aee69-e5e3-4e08-9684-33b3f36e529d"
    }}, secret, algorithm="HS256")
print(jwt_token)

Limitations

1. The external version of the Transcript Editor (under the URL of api.deepva.com/transcript-editor) is designed for external users without the need of a DeepVA account, respectively without an active DeepVA login session. One notable limitation in the external Transcript Editor is its behavior when accessing the page while already logged into the DeepVA frontend. If a user with an active DeepVA session attempts to access the Transcript Editor, they will be automatically redirected to the Job Overview page instead of the intended Transcript Editor. This behavior assumes that the user is a non-DeepVA user without an active session. To accurately test the Transcript Editor without encountering this redirection, it is recommended to either use a different browser or switch to private browsing mode, where no active DeepVA session is present.