Management license

Introduction

This section describes BSS communication with AminoTV License v4 API. Products and user licenses are manageable through License Management API. 

The license management API consist of two parts: licenses management and products management.

Entities

License resource

Typical license resource may look like the one below and it consists of 3 parts.

{
  "id": "42",
  "type": "License",
  "attributes": {
    "status": "ACTIVE",
    "start_date": 1523268666,
    "stop_date": 1523268698,
    "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
    "renew_record": {
      "recurring": true,
      "expiry_date": 1523268698
    },
    "purchase_record": {
      "price_currency_amount": 1223,
      "price_currency_iso4217": "EUR",
      "purchase_timestamp": 1526648593,
      "payment_method": "credit card"
    }
  },
  "relationships": {
    "user": {
      "data": {
        "id": "41",
        "type": "User"
      }
    },
    "product": {
      "data": {
        "id": "41",
        "type": "Product"
      }
    }
  }
}

Resource identification:

• id - unique license resource identifier - auto generated value, this value is used when operating over license

• type - resource type, must be 'License' 

Attributes:

• status - current license status, could be one of [PROCESSING, CHECK_INVALID, ORDER_ERROR, ACTIVE, EXPIRED, SUSPENDED, SUSPENDEDADMIN]:
  • ACTIVE - this is the only status which allows end-user to watch the content license was created for, it is default status for newly created o licenses
  • SUSPENDED - license was suspended by client through BSS or by AminoTV support via CMS
    
  • SUSPENDEDADMIN - license was suspended by AminoTV script
    
  • EXPIRED - license life time expired, managed by AminoTV scripts
    
  • ORDER_ERROR, CHECK_INVALID, PROCESSING - are internal statuses for matching orders with external systems (Hybris SAP)
    
• start_date - timestamp when the license should become active
  
• stop_date - timestamp when the license will expire
  
• order_id - field used to store client generated order id, also used by internal scripts when purchacing/prolonging licenses with 3rd party services
  
• renew_record.recurring - with setting this attribute client can specify should the license be auto renewable or not, if the attribute omitted then value from associated product used.
  
• renew_record.expiry_date - expiration date of the licenses, if the renew_record.recurring attribute set to true then licenses renewal scripts will rely on this attribute to select licenses to process
  
• purchase_record.price_currency_amount - price of the license in cents, if this is not provided the value from associated product will be used
• purchase_record.price_currency_iso4217 - currency of the license price, if this is not provided the value from associated product will be used
  
• purchase_record.purchase_timestamp - timestamp to set license purchase date, this could be useful when license created separately on client side and then added to system, if no value provided then current timestamp will be used
  
• purchase_record.payment_method - the method license was payed with, as we do not support any billing system clients should manage payments processing by themselves and can just pass any convenient string here. Please note that for users license API payment method 'billing' will be used by default.
  

Relationships:

• user - user identifier identifier and type 'User' to grant license

• product - product identifier and type 'Product' to associate license with

Product resource

Product resource may looks like one below.

{
  "id": "41",
  "type": "Product",
  "attributes": {
    "title": "Sport channels meagpack",
    "description": "Complete collection fo all sports channels",
    "is_premium": true,
    "price_record": {
      "amount": 98,
      "currency": "EUR"
    },
    "license_duration": 518400,
    "type": "CATCHUP",
    "auto_grant_on_signup": false,
    "auto_renew": false,
    "is_user_visible": true,
    "is_buyable": true
  },
  "relationships": {
    "live": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    },
    "catchup": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    },
    "npvr": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    },
    "startover": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    }
  }
}

Resource identification:

• id - unique product resource identifier - auto generated value, this value is used when operating over license

• type - resource type, must be 'Product' 

Attributes:

• title - required product title 

• description - optional product description

• is_premium - optional, flag to identify product as premium, used by packages import scripts, false by default

• price_record.amount - required product price in cents

• price_record.currency - required product price currency

• license_duration - required duration in seconds to use as default when issuing license n this product

• type - type of package, could be one of: 
  • CATCHUP - product contains only catchup items
  • CHANNEL - product contains able channel items
  • PVR - product contains only npvr items
  • STARTOVER - product contains only starter items
  • CHANNEL_GROUP - product contains mixed items

• auto_grant_on_signup - defines should license on this product be issued for every new user created

• auto_renew - defines should the license issued for that product be recurring or not

• is_user_visible - defines should users see the product in the list of available 

• is_buyable  - defines should users be able to purchase this product
  
  

Authorization

All BSS endpoints support API key authorization. The header named 'Authorization' with content "Apikey PUT_YOUR_KEY_HERE" must be passed with request.

Licenses management

Fetch licenses

Endpoints overview

BSS can get list of licenses with filters, all user licenses and single license. GetLicenses and GetLicenseById calls return an array of licenses with all relationships and also contain included section with all products associated to fetched licenses. GetLicenseById will return single license resource and associated product in included section.

Create licenses

Delete licenses

Batch operations

Products management

Fetch products

Create products

Update products

Delete products

Use cases

Migration from legacy

DRM provers support

Irdeto