Client Authentication

The client-side application is more susceptible to security vulnerabilities that it can be exploited by an attacker to perform unintended actions, such as injecting malicious code or stealing user data. As the client-side application runs on a user's device, it is also more prone to threats like malware, phishing attacks, etc. Dolby.io platform provides APIs to safeguard client access and mitigate operational risks.

The client SDKs provide various variants of the initializeToken API, which enable authentication of the client-side application against the service. These methods accept a client access token as input, which can be obtained by your backend application from the REST API. If you do not have a backend application, you can generate a client access token, that is valid for 24 hours, from the developer dashboard. Typically, an application requests an API token with a longer validity period (e.g. 24 hours), stores it in a secure location, and reuses it instead of acquiring a new API token each time a client access token is created.

Obtain a client access token using REST API

To obtain a client access token, use an API token with the comms:client_access_token:create scope.

import asyncio
import os
# Install the dependency dolbyio_rest_apis
# https://pypi.org/project/dolbyio-rest-apis/
# python3 -m pip install dolbyio-rest-apis
from dolbyio_rest_apis import authentication
from dolbyio_rest_apis.communications import authentication as comms_authentication

APP_KEY = os.environ['APP_KEY']
APP_SECRET = os.environ['APP_SECRET']

loop = asyncio.get_event_loop()

# Request an API token
task = authentication.get_api_token(
    APP_KEY,
    APP_SECRET,
    600,
    ['comms:client_access_token:create']
)
api_token = loop.run_until_complete(task)

# Request the Client Access Token
task = comms_authentication.get_client_access_token_v2(
    api_token.access_token,
    session_scope=['conf:create', 'notifications:set'],
    external_id='[email protected]'
)
client_access_token = loop.run_until_complete(task)
// Install dependency @dolbyio/dolbyio-rest-apis-client
// npm install @dolbyio/dolbyio-rest-apis-client
const dolbyio = require('@dolbyio/dolbyio-rest-apis-client');

const APP_KEY = process.env.APP_KEY ?? '';
const APP_SECRET = process.env.APP_SECRET ?? '';

const apiToken = await dolbyio.authentication.getApiAccessToken(
    APP_KEY,
    APP_SECRET,
    600,
    ['comms:client_access_token:create']
);

const accessToken = await dolbyio.communications.authentication.getClientAccessTokenV2({
    accessToken: apiToken,
    externalId: '[email protected]',
    sessionScope: ['conf:create', 'notifications:set'],
});

Obtain a client access token using the dashboard

To acquire a client access token from the dashboard, select your preferred application, navigate to the client access token section, and copy the token. This token automatically expires after 12 hours.

Scope

Similar to the scope of API tokens, client access token also supports scope-based access control to ensure greater precision in access control. The client access token scope is required. For a list of supported scopes, please refer to the REST API reference.

Client identification

The optional externalID in the API request allows you to assign a unique identifier for each participant. This ID can be a free-form string with a limit of 1,024 bytes. This flexible scheme allows for supplementary metadata information to the local participant's identity in your application.

Without providing an external ID you can still initiate a session and connect to a conference, but you are not able to verify the participant's identity in the conference.

Size limit

The client access token is a Base64-encoded JSON Web Token (JWT) with a maximum size limit of 2,048 bytes. The provided participant information may cause exceeding this limit. In this case, the API returns an error message requesting you to reduce the size.

Validity period

During the client access token request, you can specify the desired validity period of the token. When the token nears its expiration, the SDK will alert your application to acquire a new token, which can then be passed back to the SDK for uninterrupted operation. To mitigate risk, we advise not setting the validity period for over 12 hours. The maximum period that you can set is 24 hours.

SDK compatibility

Currently, the client SDKs provide session.open() APIs that enable self-identification by the client-side application. However, since this mechanism is vulnerable to impersonation attacks, we intend to deprecate this API in the future. If participant identity has been specified in the client access token request, the system will disregard any participant information provided through the client-side session.open() API.