Authorize a user¶

A user must be authorized to watch paid content (SVOD, TVOD, DTO). This guide shows how to get an access token for a user. It also shows how to use the token in the Content API requests.

Before you start¶

Make sure that:

You have the partner ID, the salt and a key pair. See Credentials.
Your code can sign requests. See Sign a request.
The user exists in the MEGOGO billing. Do one of these:
- Record a subscription or a purchase. See Sell a subscription and Sell a single title.
- Create the user without a service: GET https://billing.megogo.net/partners/{partner_id}/user/create?identifier={user_id}. Use this request if the user must sign in before the purchase.

The flow¶

sequenceDiagram
    participant App as Partner application
    participant Server as Partner server
    participant Billing as MEGOGO Billing API
    participant API as MEGOGO Content API
    Server->>Billing: subscription/subscribe (user identifier, service ID)
    Billing-->>Server: "successful": true
    Server->>API: GET /auth/by_partners (isdn, partner_key, token, sign)
    API-->>Server: access_token
    App->>Server: Request to play a video
    Server-->>App: Signed URL of /stream with access_token
    App->>API: GET /stream
    API-->>App: src (manifest URL)

Step 1. Calculate the authorization token¶

On your server, calculate the MD5 hash of the user identifier, the partner ID and the salt. Join them with no separator:

token = md5(user_id + partner_id + salt)

Example with invented values:

Value	Example
User identifier	`user-0001`
Partner ID	`examplepartner`
Salt	`examplesalt`
Text for the hash	`user-0001examplepartnerexamplesalt`
`token`	`694ebeecfb23fd2331b76712d53e3017`

Use the same user identifier as in the Billing API requests (userId). Use an identifier that does not change, for example the internal ID of the user in your system.

CAUTION

Send the authorization request only for a user that you created in the Billing API (a purchase or user/create). The authorization request does not check the billing. If MEGOGO does not know the user identifier, the request makes a new MEGOGO account without services.

Step 2. Send the authorization request¶

GET https://api.megogo.net/v1/auth/by_partners?isdn={user_id}&partner_key={partner_id}&token={token}&sign={sign}

Parameter	Required	Description
`isdn`	Yes	The user identifier on your side
`partner_key`	Yes	Your partner ID
`token`	Yes	The token from step 1
`sign`	Yes	The signature of `isdn`, `partner_key` and `token`, in this order

Example with the invented values and the keys from Sign a request:

https://api.megogo.net/v1/auth/by_partners?isdn=user-0001&partner_key=examplepartner&token=694ebeecfb23fd2331b76712d53e3017&sign=0f80aec18dba20019775d90bad5e1020_example1_xx

Step 3. Read the access token¶

Expected response (shortened):

{
  "result": "ok",
  "code": 200,
  "data": {
    "user_id": 1234567,
    "tokens": {
      "access_token": "{access_token}",
      "access_token_expires_at": 1793300000,
      "remember_me_token": "{remember_me_token}",
      "remember_me_token_expires_at": 1951000000
    }
  }
}

Field	Description
`user_id`	The MEGOGO user ID
`tokens.access_token`	Add it to the requests that need the user
`tokens.access_token_expires_at`	The end of the access token, Unix time (UTC). About 6 hours after the request
`tokens.remember_me_token`	A long-term token. Use it to get a new access token (step 5)
`tokens.remember_me_token_expires_at`	The end of the long-term token, Unix time. About 5 years after the request

The response also has profile fields and other fields, for example is_new_user. Do not use them.

WARNING

Keep the access token as safely as a password. Do not write it in logs. With the token, a person can watch the paid content of this user.

Step 4. Use the access token¶

Add access_token to the requests that need the user:

/stream: to get the stream of a paid video.
/video/info: to get is_available for this user.

Include access_token in the signature, like all other parameters:

https://api.megogo.net/v1/stream?video_id={video_id}&access_token={access_token}&sign={sign}

WARNING

The stream URL in src contains data of the user. Do not write it in logs and do not keep it. Request a new src each time the user starts the playback.

Step 5. Get a new access token¶

The access token expires after about 6 hours. You decide when to get a new token, for example before the expiry time or after an error. Use one of these two methods:

Send the remember-me token to /auth/refresh.
Do steps 1–3 again.

To use the remember-me token, send this request:

GET https://api.megogo.net/v1/auth/refresh?rememberme_token={remember_me_token}&sign={sign}

CAUTION

The parameter name is rememberme_token, with one underscore. The name remember_me_token gives an error.

The response has the same structure as in step 3. Use the access_token from the response. If the previous access token is still valid, the response can contain the same access token. The remember-me token is valid for about 5 years.

Errors¶

Response	Cause	Action
HTTP 200, `"result": "error"`, `"message": "The entered login or password is incorrect"`	The `token` is not correct	Make sure that you use the same user identifier, partner ID and salt as in step 1
HTTP 400, `"message": "You entered wrong sign key"`	The signature is not correct	Make sure that the signature contains `isdn`, `partner_key` and `token` in this order. In other requests, include `access_token` in the signature
HTTP 200, `"result": "error"`, `"code": 403`	The access token is not correct or expired	Get a new access token (step 5)
`/auth/refresh`: HTTP 200, `"result": "error"`, `"code": 400`	The remember-me token is not correct, or the parameter name is wrong	Do steps 1–3 again
`/stream`: HTTP 200, `"result": "ok"`, empty `src`, `restrictions` contains `NOT_PURCHASABLE`	The user has no active service for this video in the MEGOGO billing, or `access_token` is not in the request	Make sure that the billing request was successful. See Play a video

Result¶

You have an access token for the user. With it, the user can watch the paid content that the user has in the MEGOGO billing.

To make sure that the services of the user are the same in your system and in MEGOGO, send GET https://billing.megogo.net/partners/{partner_id}/user/subscriptions?identifier={user_id}. See the Billing API reference.