/
[BSS] STB management

[BSS] STB management

Owned by Andy Beak (Unlicensed)
Last updated: May 08, 2019 by Tung Hoang (Unlicensed)

Introduction

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

This document is comprised of two sections:

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

Solution overview

There are two steps for Customer: 

  1. Create a user account
  2. 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 numberDataProvided byHow it is provided
1User account to be createdCustomer
POST https://domain.tld/api/management/user
2Serial number of the STB that was soldCustomer
POST https://domain.tld/api/management/stb/link_user
3User identity of the person the STB was sold toCustomer
POST https://domain.tld/api/management/stb/link_user
4STB serial number when logging inAminoEmbedded in a signed JWT token

(warning) 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


ActionAPI call requiredOffline business process required
1User 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
3Customer system then link the STB to that userLink user account to STB
4User go home and turn on the new STB

5STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim

6Amino API uses the JWT and the linkage from step 3 to determine which user to log in


Existing User buys new STB


ActionAPI call requiredOffline business process required
1User go to Customer store and buy a new STB
Capture user details and the STB serial number
2Customer then link the STB to the existing user accountLink user account to STB
3Optionally, Customer unlinks the old STBRemove STB Ownership from an User
4User go home and turn on the new STB

5STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim

6Amino API uses the JWT and the linkage from step 2 to determine which user to log in


Existing user sell his/her STB


ActionAPI call required
1User A sells his/her STB to user B

2User A call Customer to unlink the STB from his/her accountRemove STB Ownership from an UserCapture user details and the STB serial number
3User B call Customer to link the STB to his/her accountLink user account to STB
4Customer captures information and:
Capture user details and the STB serial number
4aUnlink the STB from user account ARemove STB Ownership from an User
4bLink the STB to user account BLink user account to STB
5User B turns STB on after being told the linking is complete

6STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim

7Amino API uses the JWT and the linkage from step 3 to determine which user to log in

Manage user entitlements


ActionAPI call required
1Entitle a user to a packageEntitle user to "A" package
2Remove entitlement from user to packageRemove 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

MethodURLAuthorization
POST
https://domain.tld/api/management/stb/link_user
IP

Parameters

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

ParametersM/ODescriptionValues
serviceOService to which the user belongs.String of service username. Shared separately.
serial_no
MSerial Number of STB. If device does not exists with provided serial no then it will be added.

Alpha numeric string.
e.g.  615507895162

email
MEmail address of user who is provisioned for using the STBValid email address.
e.g. john.doe@example.com 
public_keys
MThis may be configured to be optional in your deployment, please check with your account manager
chipset_idOSTB device chipset number/ID.chipset_id is a random list of characters (max 32 characters).
macOEthernet interface MAC address.mac is a random list of characters (max 18 characters).

Response

HTTP CodeResponse
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"
  }
}
401none

Error Codes

Error CodeDescription
1414Email does not exist
1426Parameter is required
1427Invalid length of chipset_id
1428Invalid length of mac
1433STB exists and linked
1434Record already exists for value
1435STB is already assigned
1436Invalid 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

MethodURLAuthorization
POST
https://domain.tld/api/management/stb/unlink_user
IP

Parameters

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

ParametersM/ODescriptionValues
service_tokenOToken generated for a service. This param will be skipped if Service-Token HTTP Header exists.
serial_no
MSerial Number of STB.

Alpha numeric string.
e.g.  615507895162

email
MEmail address of user who is provisioned for using the STBValid email address.
e.g. john.doe@example.com 

Error Codes

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

Related content