Introduction

This page details all of the BSS integration points to manage STB and users.

This document is comprised of two sections:

An overview of the user stories - User Stories - business integration
A more detailed exploration of each call that the customer needs to make - Details of calls

Solution overview

There are two steps for Customer:

Create a user account
Link the STB to the user account

Details of exactly how to do this are given below on this page.

The STB will be able to identify itself to Amino API, which links it to a user. Details of how this works are available at (BSS) Passwordless STB login

Summary of data integration

This table summarizes the data we need

Item number	Data	Provided by	How it is provided
1	User account to be created	Customer	POST https://domain.tld/api/management/user
2	Serial number of the STB that was sold	Customer	POST https://domain.tld/api/management/stb/link_user
3	User identity of the person the STB was sold to	Customer	POST https://domain.tld/api/management/stb/link_user
4	STB serial number when logging in	Amino	Embedded in a signed JWT token

Note: Items 2 and 3 are supplied in the SAME call to link_user, there is not a duplicate call made

User Stories - business integration

New User buys new STB

	Action	API call required	Offline business process required
1	User go to Customer store and buy a new STB		Capture user details and the STB serial number
2	Customer system then provision new user	Create user account
3	Customer system then link the STB to that user	Link user account to STB
4	User go home and turn on the new STB
5	STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim
6	Amino API uses the JWT and the linkage from step 3 to determine which user to log in

Existing User buys new STB

	Action	API call required	Offline business process required
1	User go to Customer store and buy a new STB		Capture user details and the STB serial number
2	Customer then link the STB to the existing user account	Link user account to STB
3	Optionally, Customer unlinks the old STB	Remove STB Ownership from an User
4	User go home and turn on the new STB
5	STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim
6	Amino API uses the JWT and the linkage from step 2 to determine which user to log in

Existing user sell his/her STB

	Action	API call required
1	User A sells his/her STB to user B
2	User A call Customer to unlink the STB from his/her account	Remove STB Ownership from an User	Capture user details and the STB serial number
3	User B call Customer to link the STB to his/her account	Link user account to STB
4	Customer captures information and:		Capture user details and the STB serial number
4a	Unlink the STB from user account A	Remove STB Ownership from an User
4b	Link the STB to user account B	Link user account to STB
5	User B turns STB on after being told the linking is complete
6	STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim
7	Amino API uses the JWT and the linkage from step 3 to determine which user to log in

Manage user entitlements

	Action	API call required
1	Entitle a user to a package	Entitle user to "A" package
2	Remove entitlement from user to package	Remove user entitlement to "A" package

Details of calls

Link user account to STB

Flow diagram (non-technical)

title Link user account to STB

note right of Customer
    Customer captures user account
    and the STB serial number
end note
Customer->Move API: POST https://domain.tld/api/management/stb/link_user
Move API->Customer: 200 OK

Technical details

Customer will POST to https://domain.tld/api/management/stb/link_user

Request

Method	URL	Authorization
POST	https://domain.tld/api/management/stb/link_user	IP

Parameters

Please note that M is for Mandatory and O is for Optional.

Parameters	M/O	Description	Values
service	O	Service to which the user belongs.	String of service username. Shared separately.
serial_no	M	Serial Number of STB. If device does not exists with provided serial no then it will be added.	Alpha numeric string. e.g. 615507895162
email	M	Email address of user who is provisioned for using the STB	Valid email address. e.g. john.doe@example.com
public_keys	M	This may be configured to be optional in your deployment, please check with your account manager
chipset_id	O	STB device chipset number/ID.	chipset_id is a random list of characters (max 32 characters).
mac	O	Ethernet interface MAC address.	mac is a random list of characters (max 18 characters).

Response

HTTP Code Response

200

{

	"id": "123",
	"serial_no": "CUS-STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@cusstb.com"
	}
}

400

{
  "error" {
    "code": 9,
    "text": "Access to this resource is locked to IP addresses"
  }
}

401 none

Error Codes

Error Code	Description
1414	Email does not exist
1426	Parameter is required
1427	Invalid length of chipset_id
1428	Invalid length of mac
1433	STB exists and linked
1434	Record already exists for value
1435	STB is already assigned
1436	Invalid email address format

How the user will sign in

See (BSS) Passwordless STB login

Remove STB Ownership from an User

Technical details

Customer will POST to https://domain.tld/api/management/stb/unlink_user

Request

Method	URL	Authorization
POST	https://domain.tld/api/management/stb/unlink_user	IP

Parameters

Please note that M is for Mandatory and O is for Optional.

Parameters	M/O	Description	Values
service_token	O	Token generated for a service. This param will be skipped if Service-Token HTTP Header exists.
serial_no	M	Serial Number of STB.	Alpha numeric string. e.g. 615507895162
email	M	Email address of user who is provisioned for using the STB	Valid email address. e.g. john.doe@example.com

Error Codes

Error Code	Description
1414	Email does not exist
1426	Parameter is required
1432	STB serial_number does not exist
1418	Invalid STB link, Service (Using service_token)

AminoTV API

[BSS] STB management

Introduction

Solution overview

Summary of data integration

User Stories - business integration

New User buys new STB

Existing User buys new STB

Existing user sell his/her STB

Manage user entitlements

Details of calls

Link user account to STB

Flow diagram (non-technical)

Technical details

Request

Parameters

Response

Error Codes

How the user will sign in

Remove STB Ownership from an User

Technical details

Request

Parameters

Error Codes

Related content