User Activity Vault (UAV) API documentation

There are three categories of API:

• Client APIs – used by client applications

• Operator APIs – used by operators

• Admin APIs – used for communication between modules

The categorised lists of APIs are available in Service endpoint categories.

The subdomain used for API calls is different for each external-facing API category:

• Client APIs use the api subdomain.

• Operator APIs use the operator subdomain.

Both client and operator APIs require authentication – these are detailed in the Client APIs and Operator APIs sections below.

Client APIs

OpenTV Platform uses NGINX to ensure that only authenticated clients can use client-facing APIs. It expects the client to supply the token that it received at signon, as:

• An authorization header with prefix in the value of Bearer,

• A Client-token header,

• A query string parameter in the URL, or

• If the request is a POST, token in the post arguments.

For backward-compatibility, the older MediaLive Identity Token is still supported.

NGINX validates and decodes the token and passes it on to the module as a token in the header – which is why the following API documentation may refer to token rather than the options mentioned above.

Operator APIs

All operator APIs use Keycloak to authenticate the caller before requests can be made. This is explained in detail in Accessing operator APIs using Keycloak.

If a client application tries to use an authentication token and there is an issue (for example, the token is invalid), it will receive an error response.

In such cases, the HTTP status is 403 and the error code that is returned will be 99999:403.

The response takes the following format:

{
  "resultCode": "99999:403",
  "localeMessage": "none",
  "requestId": <request_ID>,
  "result": "<error_message>"
}

The error message in the result field will tell you what the issue was. It will be one of the following:

• Bearer Token Signature Invalid

• Bearer Token Decoding Failure

• Exp Claim missing

• Bearer Token Expired

• Fixed Expiry Claim Expired

• A Token Required