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

Glossary

Actor	Who
Customer	Amino's customer
User	The customer's end user, who purchases and uses the STB
API	Amino's API

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://boox.fi/api/management/user
2	Serial number of the STB that was sold	Customer	POST https://boox.fi/api/management/stb/link_user
3	User identity of the person the STB was sold to	Customer	POST https://boox.fi/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

Overview of BSS integration phases

Phase 1: No integration, users are provisioned through CMS

Phase 2: Customer will provision users through an API as part of the vending process

Solution overview for phase 2

There are two steps for Customer. Details of exactly how to do this are given below on this page.

Create a user account
Link the STB to the user account

The STB will be able to identify itself to Amino API, which links it to a user. Details of how this works are available in the page BPLAT-6339: Passwordless STB login

Move BPLAT-6339: Passwordless STB login to MAPI, update link

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 new user
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

Create new user

This API is used to add a new user account. Following rules apply:

Email address or customer-id should not belong to any customer that is not in DELETED state; otherwise API will return an error.
If the user with that email exists in DELETED state and his grace period is not expired, his previous registration state is restored.
A new user is created in UNREGISTERED state.

Flow diagram

title Create new user account

Customer->Move API: POST https://boox.fi/api/management/user
Move API->Customer: 200 OK

Technical details

Request

Method Type	URL	Authorization
POST	`https://boox.fi/api/management/user`	Service (Digest Authentication)

Query Strings

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

Parameter	M/O	Description	Values
service	M	Service to which the user belongs.	String of service username. Shared separately.
email	M	Email address of the user.	Email address of the user
cid	M	Customer Identifier.	Numeric ID linking the user to Customer system
auth_pin	M	Authentication PIN code.	Number with the length of 4. e.g. 8798
purchase_pin	M	Purchase PIN code.	Number with the length of 4. e.g. 8798
dob	O	User Date of birth in YYYY-MM-DD format.	SUSPEND or ACTIVATE keywords are allowed only.

Error Codes

Error Code	Description
1403	email is missing
1405	cid is missing
1406	auth_pin is missing
1407	purchase_pin is missing
1412	Email already exists
1413	CID already Exists

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://boox.fi/api/management/stb/link_user
Move API->Customer: 200 OK

Technical details

Customer will POST to https://boox.fi/api/management/stb/link_user

Request

Method	URL	Authorization
POST	https://boox.fi/api/management/stb/link_user	IP, Service (Digest Authentication)

Parameters

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

Parameters	M/O	Description	Values
service	M	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	8 Public keys which will be used to authenticate the STB. Public keys are stored based on the POST body order. So first public key is considered having key index 0. Last public key is considered having key index 7.	key0_base64;key1_base64;...........;key7_base64 (no limit on max length). where each public key is base-64 encoded,semicolon(;) is used between keys as separator.
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": "DNA-STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@dnastb.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 BPLAT-6339: Passwordless STB login

Remove STB Ownership from an User

Technical details

Customer will POST to https://boox.fi/api/management/stb/unlink_user

Request

Method	URL	Authorization
POST	https://boox.fi/api/management/stb/link_user	IP, Service (Using service_token)

Parameters

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

Parameters	M/O	Description	Values
service_token	M	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

STB management

Introduction

Glossary

Summary of data integration

Overview of BSS integration phases

Solution overview for phase 2

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

Create new user

Flow diagram

Technical details

Request

Query Strings

Error Codes

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