Authentication token

Do not host authentication tokens in any publicly-accessible locations (such as public source code repositories).

Doing so presents a security risk.

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:

CODE

/v3/token/actions/signOnByCasn

Parameter	Parameter Type	Data Type	Description	Required
`x-correlation-id`	header	string	ID used to correlate a specific request with a response	No
`tenantId`	header	string	ID of the tenant that the device is registered with	Yes
`casn`	body	JSON	The device's CASN identifier	Yes

Smartcard-based signon

Request

For smartcard devices, send a POST request to:

CODE

/v3/token/actions/signOnBySmartCardId

Parameter	Parameter Type	Data Type	Description	Required
`x-correlation-id`	header	string	ID used to correlate a specific request with a response	No
`tenantId`	header	string	ID of the tenant that the device is registered with	Yes
^smartCardId	body	JSON	The smartcard ID	Yes

TVKey activation signon

Request

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

CODE

/v3/token/actions/signOnByTVKeyActivation

Parameter	Parameter Type	Data Type	Description	Required	Details
`x-correlation-id`	header	string	ID used to correlate a specific request with a response	No
`tenantId`	header	string	ID of the tenant that the device is registered with	Yes
^{activationRequestMessage}	body	JSON	Activation request message	Yes
`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.

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:

XML

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

Using the following request header if required:

Header	Type	Description	Required
x-correlation-id	string	ID used to correlate a specific request with a response	No

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.

Managed device authentication

Cardless signon

Request

Smartcard-based signon

Request

TVKey activation signon

Request

Open device authentication

Request

See also