API Authentication

Overview

Dolby.io offers a common access control scheme for both Media APIs and Communications APIs.

API tokens are essential to ensure the security and privacy of data exchanged through the API. Except the API Token generation API, which uses basic authentication, all Dolby.io Media and Communications REST APIs require the use of an API token in the Bearer authorization header.

Generating an API token

Before generating an API token, you need the App key and App secret credentials from the Dolby.io developer dashboard:

  1. Log in to the Media & Communications Dolby.io developer dashboard.
  2. In the Applications section, select your application.
  3. Click Copy to copy your App key and App secret.

❗️

Note

To ensure security, store your App Secret in a secure location. If you suspect that the secret has been compromised, delete the application or contact [email protected] for assistance. Keep the API token in a secure location as well and do not share it with untrusted entities.

The following code examples show how to acquire an API token that can only read data from the Monitor API.

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

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,
    1800,
    ['comms:monitor:read']
)

access_token = loop.run_until_complete(task)
// Install the 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,
    1800,
    ['comms:monitor:read']
);
using System;
// Install NuGet package DolbyIO.Rest
// https://www.nuget.org/packages/DolbyIO.Rest
// dotnet add package DolbyIO.Rest
using DolbyIO.Rest;
using DolbyIO.Rest.Models;

public async Task<JwtToken> GetApiAccessTokenAsync()
{
    string appKey = Environment.GetEnvironmentVariable("APP_KEY") ?? throw new Exception("APP_KEY is missing");
    string appSecret = Environment.GetEnvironmentVariable("APP_SECRET") ?? throw new Exception("APP_SECRET is missing");

    using DolbyIOClient client = new DolbyIOClient();

    return await client.Authentication.GetApiAccessTokenAsync(
        appKey,
        appSecret,
        1800,
        new string[] {
            "comms:monitor:read"
        }
    );
}

API Token scope

The scope that is currently available only in Communications APIs is a mechanism that allows your server-side application to provide fine-grained access control. It defines the set of permissions that the token holder has to access certain resources or perform specific actions within the API. By limiting the scope of an API token, you can prevent unauthorized access and minimize the risk of data breaches and other security threats. If you do not specify the scope, the API token will possess unrestricted access to all resources and actions. There are three ways to specify the scope of an API token:

  • Defining a specific scope, such as comms:monitor:read, which only permits the token to read data from the Monitor API.
  • Defining a list of scopes, such as comms:monitor:read comms:monitor:delete, which grants the token permission to read and delete data from the Monitor API.
  • Using a wildcard, such as comms:*, which gives the token access to all Communications REST APIs.

Token validity period control

The token validity period is an important security feature that helps to protect API resources and prevent unauthorized access. By setting a finite validity period for API tokens, developers can reduce the risk of security breaches and maintain better control over access to their API. The maximum token validity period you can set is 86,400 seconds, indicating 24 hours. If no value is specified, the default is 1,800, indicating 30 minutes.