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

ActorWhoCustomerAmino's customerUserThe customer's end user, who purchases and uses the STBAPIAmino's API

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://

boox

domain.

fi

tld/api/management/user
2	Serial number of the STB that was sold	Customer	POST https://

boox

domain.

fi

tld/api/management/stb/link_user
3	User identity of the person the STB was sold to	Customer	POST https://

boox

domain.

fi

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

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

Table of Contents

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

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

Image Removed

Code Blocktheme

Midnightcollapsetrue

title Create new user account

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

Technical details

Request

Method TypeURLAuthorizationPOSThttps://boox.fi/api/management/userService (Digest Authentication)

Query Strings

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

ParameterM/ODescriptionValuesserviceMService to which the user belongs.String of service username. Shared separately.emailMEmail address of the user.Email address of the usercidMCustomer Identifier.Numeric ID linking the user to Customer system
auth_pinM

Authentication PIN code.

Number with the length of 4.
e.g. 8798 purchase_pinM

Purchase PIN code.

Number with the length of 4.
e.g. 8798 dobOUser Date of birth in YYYY-MM-DD format.SUSPEND or ACTIVATE keywords are allowed only.

Error Codes

Error CodeDescription1403email is missing1405cid is missing1406auth_pin is missing1407purchase_pin is missing1412Email already exists1413CID already Exists

Link user account to STB

Flow diagram (non-technical)

Image RemovedImage Added

Code Block

theme	Midnight
collapse	true

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

Technical details

Customer will POST to https://booxdomain.fitld/api/management/stb/link_user

Request

Method	URL	Authorization
POST	https://booxdomain.fitld/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

MO

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.

Note

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.

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": "DNACUS-STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@dnastbuser@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 BPLAT-6339: (BSS) Passwordless STB login

Remove STB Ownership from an User

Technical details

Customer will POST to https://booxdomain.fitld/api/management/stb/unlink_user

Request

Method	URL	Authorization
POST	https://

boox

domain.

fi

tld/api/management/stb/

link

unlink_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	MO	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)

Version	Old Version 48	New Version Current
Changes made by	Andy Beak (Unlicensed)	Tung Hoang
Saved on	Oct 18, 2018	May 08, 2019

Versions Compared

Key

Introduction

Glossary

Solution overview

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

Midnightcollapsetrue
title Create new user account Customer->Move API: POST https://boox.fi/api/management/user Move API->Customer: 200 OK

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

Page Comparison

Versions Compared

Key

Introduction

Glossary

Solution overview

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

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

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

Midnightcollapsetrue
title Create new user account Customer->Move API: POST https://boox.fi/api/management/user Move API->Customer: 200 OK