Magine Documentation

Introduction

Tokens

Magine AccessToken

Magine AccessToken is the unique identifier we assign to each of our partners. It might look, for example, like this: 25b70ae1-d2bd-4ae7-85f4-62026580c866. Note that the Magine AccessToken is used to identify you as a partner, and not to authenticate a user.

User Authorization Token

User Authorization Token is a JWT Bearer. This token is returned by the authorisation API's and will is used to authorise the user in all subsequent API calls.

Entitlement Token

Entitlement Token is used to intiate playback, can be retrieved from the Entitlement API.

Reset Password Token

Reset Password Token is generated when triggering a password reset. It is used to validate the setting of a new password through the Reset Password API.

Examples

Register a user

The first step you will want to take to use our platform is creating a user. For this step, there is only one prerequisite: a Magine AccessToken.

Here is the minimum necessary cURL command you need to run in order to create a user:

        curl -XPUT 'https://client-api.magine.com/api/login/v2/auth/email' \
        -H 'Magine-AccessToken: [PARTNER-MAGINE-ACCESSTOKEN]' \
        --data-binary '{"identity":"[USER-EMAIL-ADDRESS]","accessKey":"[USER-PASSWORD]","name":"[NAME-OF-USER]"}'
        

Save the userId and the generated User Authorization Token. You will need them in the queries to come.

For more fields and further documentation, check out the complete API description at: https://tvoli.github.io/generated/login/login.html

Authenticate/Login a user

The same service as used in the previous section is also used to authenticate the user

Below is a minimal cURL command to login a user (notice the switch from PUT to POST, the URL is the same):

        curl -XPOST 'https://client-api.magine.com/api/login/v2/auth/email' \
        -H 'Magine-AccessToken: [PARTNER-MAGINE-ACCESSTOKEN]' \
        --data-binary '{"identity":"[USER-EMAIL-ADDRESS]","accessKey":"[USER-PASSWORD]"}'
        

How to reset a users password

To reset a user password, you first has to ask the user for the email. When you have the email, you can send a POST to /api/login/v2/password/send-reset-password with a body of {"email":"...","locale":"de"}.

Our API endpoint will send out an email if the user exists. In the email it will be a token that is short-lived.

The API endpoint to send the new password + the token from the email is available at /api/login/v2/password/reset with a body of {"password":"...","token":"[Reset Password Token]"}

Example cURLs

curl -XPOST https://client-api.magine.com/api/login/v2/password/send-reset-email \
        -H 'Magine-AccessToken: [Magine AccessToken]' \
        -d '{"email":"...","locale":"de"}'

curl -XPOST https://client-api.magine.com/api/login/v2/password/reset \
        -H 'Magine-AccessToken: [Magine AccessToken]' \
        -d '{"password":"...","token":"[Reset Password Token]"}'

Playback

Magine provides a set of services for the client and player to interact with to be able to play content.

• Entitlement
• Playback
• Playlist
• Fragment
• Telemetry

Features

Magine's platform support the following DRM and streaming protocols.

DRM

• Widevine Modular
• Fairplay
• Playready

Streaming Protocols

• MPEG-DASH
• HLS
• Microsoft Smooth Streaming

Which can be combined in the following manner

	MPEG-DASH	HLS	Microsoft Smooth Streaming
Widevine Modular	x
Fairplay		x
Playready	x		x

Playing a stream

Starting a stream

To be able to play content, the client first needs to require an Entitlement Token', providing proof the user is allowed to play the video asset. An Entitlement token can be requested from the entitlment service.

curl -X POST https://client-api.magine.com/api/entitlement/v2/asset/AssetId \
            -H 'Magine-Accesstoken: Magine AccessToken' \
            -H 'Authorization: Bearer User Authorization Token'

The next step for the client is to issue a preflight request against the playback service.

curl -X POST https://client-api.magine.com/api/playback/v2/preflight/asset/AssetId \
              -H 'Magine-Accesstoken: Magine AccessToken' \
              -H 'Authorization: Bearer User Authorization Token' \
              -H 'Magine-Play-DRM: Drm' \
              -H 'Magine-Play-Protocol: Protocol' \
              -H 'Magine-Play-EntitlementId: Entitlement Token' \
              -H 'Magine-Play-DevicePlatform: Platform' \
              -H 'Magine-Play-DeviceType: Type' \
              -H 'Magine-Play-DeviceModel: Model' \
              -H 'Magine-Play-DeviceId: Id'

The response of the preflight request will provide the client with the URLs for license and playlist needed to be able to start playback as well as heartbeat for sending updates to the API.

The client now needs to make a request for fetching the license throught the license URL as well as getting a playlist/Manifest throught the playlist URL. After succeeding with those two requests, the player will be able to start and decrypt the DRM protected stream.

For a Widvine request, the license URL might be the following

https://client-api.magine.com/api/playback/v1/widevine/license

The playlist URL for a Dash Manifest could be

http://d2njhtu7w6ua6u.cloudfront.net/11245/000000000000001e000000008256c69c_Manifest.mpd

While playing a stream

The Magine platform currently requires the player to send a heartbeat every 10 seconds.

curl -X POST https://client-api.magine.com/api/playback/v1/heartbeat
              -H 'Magine-Accesstoken: Magine AccessToken' \
              -H 'Authorization: Bearer User Authorization Token' \
              -H 'Magine-Play-DRM: Drm' \
              -H 'Magine-Play-Protocol: Protocol' \
              -H 'Magine-Play-EntitlementId: Entitlement Token' \
              -H 'Magine-Play-DevicePlatform: Platform' \
              -H 'Magine-Play-DeviceType: Type' \
              -H 'Magine-Play-DeviceModel: Model' \
              -H 'Magine-Play-DeviceId: Id' \
              -H 'Magine-Play-Session: Session' \
              -H 'Magine-Play-Timestamp: Timestamp' \
              -H 'Magine-Play-Bitrate: Bitrate' \
              -H 'Magine-Play-ResolutionWidth: Width' \
              -H 'Magine-Play-ResolutionHeight: Height'

The player is also required to report certain events to the the Telemetry service.

curl -X POST https://client-api.magine.com/api/tracker/v1/telemetry-events
              -H 'Magine-Accesstoken: Magine AccessToken' \
              -H 'Authorization: Bearer User Authorization Token' \
              -d '[{"timestamp": 1235587,"source": "APP_ACTION","component": "/player/engine","action": "playback_buffering","seqId": 1,"context": {"playback_buffering_type" : "initial","duration": 12,"playlist_url": "http://www.magine.com/api/foo/bar","asset_id": "r5345-345345-345dczv","playback_bitrate": 34645,"playback_position": 0,"network_type": "wifi","device_type": "smartphone","device_model": "iphone 6","device_platform": "apple","device_id":"d2453ergdfzv-reagfdzgbx-fdg","app_build": 123,"app_version": "1.26"},"extra": {"player_version": "0.1"}}]'

Youth Protection

For VOD and catch-up, the youth protection is done by the Entitlement service. Should a user be required to enter a pin code to watch a blocked program, the entitlment request will be denied with an error code instructing the client to request a code from the user.

For live, the player is required to do a request against the entitlement service every time a new program beginns in the live stream or the user timeshifts(fast forwards or rewinds) to another program in the stream. If the enitlement respons indicates that the program is blocked for the user, the client needs to stop the stream and ask the user for a pin code to continue watching. If the user has already unlocked a program he/she doesn't need to provide a pin code for it again during the same player session. But if there are two consecutive programs or more that require a pin code in the same session, the user needs to enter a pin code for each and every one of the unique programs.

Blackout in live

Because of right issues, a program might lack the rights to be broadcasted live on a channel that otherwise has live rights. Therfore the player needs to listen to the response of the Heartbeat request. In this case a 552 error repsonse will be returned.

Service APIs

• Telemetry
• Login
• Parental-Control
• Subscription
• Entitlement
• User
• Geoip
• Playback-Api
• Nibble-Api
• Schedule-Api
• My-List

Client SDK APIs

• iOS-MagineWhiteLabel
• iOS-MagineKitSDK
• iOS-MagineKitPlayer
• Android-SDK

Web SDKs

All our SDKs are published on NPM as private packages. In order to get access to the following links, you will need to ask for access for your npm accounts.

We're using React for our internal web projects, so expect optimizations for it in our SDKs.

Javascript API client

A javascript framework around the API calls provided by the backend. Integrate this and get automatic updates on your API calls.

JS API client

Hipster player

An HTML5 player based on Dash and HLS (for Safari). Not optimized for mobile, but it is a fast and easy way to get your content running!

Puts the hip in the hippopotamus

Hipster player