Overview

This is the User and Asset Organizer. It is responsible for authenticating users or devices and keeping track of their assigned assets.

UAO's primary purposes are:

Authenticating credentials, returning the corresponding user id.
Returning assets for given user ids.

It does not do any authorization by itself. Actually limiting access based on the assets returned by UAO must be handled by other services.

System Setup

On a SnapTV Server, install snaptv-uao-api and snaptv-webinterface:

sudo apt-get install snaptv-uao-api snaptv-webinterface

The admin interface

The SnapTV server has a web based admin interface at http://<Server IP>

There is a graphical UAO interface at http://<Server IP>:5052/uao/admin/. This allows you to create products, users and user devices.

Using the API

Download the SSL API Key from the server's admin interface (under System configuration).

Then, access the API methods as shown below, but with the server address instead of "localhost" e.g:

curl -kE <API key path> https://<server ip>/

This page uses curl in the examples. You will have to adapt them to whatever tool you are using.

The provisioning API

This is a system-facing API, used for programmatic configuration of users, assets and user devices. It basically lets you access the same functionality as the admin interface but much simpler if you are a computer or just really like using the shell.

Create user:

curl -X PUT 'localhost:5051/uao/registration/users/1337' -d description='test'

Add STB:

curl -X PUT 'localhost:5051/uao/registration/users/1337/stbs/start-pair/1234-5678'

List registered STBs:

curl 'localhost:5051/uao/registration/users/1337/stbs/'

List channels:

curl 'localhost:5051/uao/registration/assets/channels/'

Define a channel pack. This step is the only one that doesn't work out of the box. It assumes that the channel exists in the database, which normally happens if you are running snaptv-uao on a gateway where you have tuned something.

Repeat the -d's to add more channels:

curl -X PUT 'localhost:5051/uao/registration/assets/channelpacks/foo' -d channels=test.snap.tv

List channel packs:

curl 'localhost:5051/uao/registration/assets/channelpacks/'

Add access to the channel pack for the user:

curl -X PUT 'localhost:5051/uao/registration/users/1337/assets/channelpacks/' -d packs=foo

Delete all STBs for a user:

curl -X DELETE 'localhost:5051/uao/registration/users/1337/stbs/'

Delete the user:

curl -X DELETE 'localhost:5051/uao/registration/users/1337'

Master Products [/uao/registration/assets/master-prodcts/]

List Master Products [GET]

Response 200 (application/json)

{
  "products": [
    {
      "id": "4b3bfb21-fc0c-4222-9460-effa458f71f1",
      "name": "Basic",
    }
  ]
}

User STBs

User STB collection [/uao/registration/users/{id}/stbs/]

List STBs [GET]

Response 200 (application/json)

{
  "stbs": [{
    "activation_code": "1111-2222-3333",
    "uid": 1040}
  ]
}

User STB [/uao/registration/users/{id}/stbs/{stbid}]

Delete STB [DELETE]

Response 204

User assets [/uao/registration/users/{id}/assets/{?expand}]

List assets for user [GET]

List all assets assigned to the user. The listed assets may be of any type.

Parameters
expand: true (optional) - If true, both directly owned, included and free for all assets are listed.

Response 200 (application/json)

{
  "assets": [
    "4b3bfb21-fc0c-4222-9460-effa458f71f1",
    "e490ee6c-6966-4488-9acd-b5e219cf0fb3"
  ]
}

Set assets for user [PUT]

Set the complete list of assets for a user. This replaces any previously set list. The ids provided as arguments may belong to any asset type.

Example:

curl -X PUT 'localhost:5051/uao/registration/users/1337/assets/ -d assets=864f0c68-c630-40e8-bdb7-8dbcebb5d10b

Request (application/x-www-form-urlencoded)

assets=864f0c68-c630-40e8-bdb7-8dbcebb5d10b&assets=e490ee6c-6966-4488-9acd-b5e219cf0fb3

Response 200 (application/json)

{
  "assets": [
    "864f0c68-c630-40e8-bdb7-8dbcebb5d10b",
    "e490ee6c-6966-4488-9acd-b5e219cf0fb3"
  ]
}

The public API

The public API is, for legacy compatibility, available to anyone, although this is only required for stacks using the legacy portal. This API supports the main UAO features: Authentication and asset provisioning.

Registering using single use activation codes

By creating an activation code for a device, it can be registered in the system by the end user. This is highly convenient for the system operator, since no information about the device needs to be added by the operator. If the operator is not using the provisioning API, an arbitrary number of activation codes can be created per user in the admin interface by selecting the Batch generate option.

The activation code is single use and disappears when successfully used to activate a device.

curl -X POST 'localhost:5050/uao/user/register?activation_code=magic&comment=foo'

A successful activation will return an api token, used to authenticate the device when communicating with UAO:

{
    "api_token": "55913d17-5d63-44c7-86dc-081e24f07b0b"
}

Registering using pre-registered hardware information

By filling the serial and mac fields for a device in the admin interface, the device can automatically register itself with the system. The comment argument is optional.

curl -X POST 'localhost:5050/uao/user/register?mac=00:00:00:00:00:aa&serial=123&comment=foo'

A successful activation will return an api token, used to authenticate the device when communicating with UAO:

{
    "api_token": "55913d17-5d63-44c7-86dc-081e24f07b0b"
}

Getting a user id

curl 'localhost:5050/uao/user/uid?api_token=55913d17-5d63-44c7-86dc-081e24f07b0b'

Returns the user id, which is used for all other endpoints:

{
    "uid": 1
}

Listing channels

curl 'localhost:5050/uao/user/live?uid=1'

Returns the list of available channels:

{
    "channels": [{
        "id": "channel.snap.tv"
    }]
}

Listing nPVR quota

curl 'localhost:5050/uao/user/npvr/quota?uid=1'

Returns the total number of seconds the user has access to:

{
    "quota": 36000
}