Authentication token

Access to most services in the OpenTV platform requires an authentication token which can be obtained by calling the token API on IAS. The OpenTV platform supports OAuth v2 workflows for authentication.

This page explains how to get the initial authentication token. For instructions on requesting a refesh token, see Refresh token.

Managed device authentication

For authentication purposes, managed devices are any devices that have NOCS (Nagra On-Chip Security); devices without NOCS (such as Android STBs) should be treated as open devices. Managed devices are typically pre-provisioned, in that the device and security device information are already present in the OpenTV platform at the time of authentication. 

There may be alternative, solution-specific mechanisms to dynamically provision managed devices, however they are not described here.

Cardless signon

Request

For non-smartcard devices, send a POST request to:

/v3/token/actions/signOnByCasn

Smartcard-based signon

Request

For smartcard devices, send a POST request to:

/v3/token/actions/signOnBySmartCardId

smartCardId

TVKey activation signon

Request

To send a TVKey activation request (which also signs the device on), send a POST request to:

/v3/token/actions/signOnByTVKeyActivation

activationRequestMessage

Open device authentication

Open devices are typically not pre-provisioned as a service provider is not usually involved in the management of the customer open device. The typical scenario is that the customer already owns an open device such as a tablet or smartphone, has downloaded the service provider's application, and now wants to use it. Therefore at first authentication, the system only has information about the user and their account, not the device itself.

Request

Send a POST request to:

https://<server>:<port>/ias/v3/token/actions/signOnByUserNamePassword

Using the following request header if required:

and the following request parameters:

Parameter	Parameter Type	Data Type	Description	Required	Details
username	body	string	Username	Yes
password	body	string	User password	Yes
clientId	body	string	A unique device identifier if available	No	For first signon, do not specify clientId. It will be assigned in the response. In this first request, you must include deviceInformation (see below) to give the head-end the information it requires to add the new device. For subsequent signons, use the client_id that was returned in the response to the first signon request. Be careful – the parameter that you submit is called clientId, but the one that is returned is called client_id. Note that if the client does not have the client_id (which can happen, for example, when the app is uninstalled and then reinstalled on the device), it should make the signon request with deviceInformation and without clientId to re-register the device. If the SSP Device Authentication Service (DAS) is not being used, this increments the device count for the account, which may cause the account device limit to be exceeded.
deviceInformation	body	JSON	Device information in a JSON object structure	No	Device information must be provided at first authentication or the request will fail. Device information should be supplied at every application launch but is not required on token refresh.

If you are limiting the number of approved devices per account, signing on using this endpoint will automatically add the device to the account's approved devices list if:

• The list is not already full, and
• The device is not already on the list.

See also

For full details of these APIs, see Identity Authentication Service (IAS) API documentation.