Implementing the "Login Flow API"

Applicaster integrates with various authentication providers like Cleeng, Inplayer, and MPX. Although it supports oAuth2, customers sometimes need a custom login implementation for more control over their login flow. This guide explains how to implement your custom API and integrate it with Applicaster's login flow, taking advantage of our pre-existing Login UI for both mobile and TV devices.

tip

The Login Flow API allows customers to connect their login API to a customized web app built by Applicaster. We chose a web-based approach rather than a native one to offer the same UI from the browser when logging into our TV platforms using Pin & Pair with a QR code.

Implementing the API Endpoints

note

You'll need to create API endpoints for the Login, Register, Reset Password, Refresh Token, and Delete Account actions. These endpoints will be used to configure the Login Flow plugin in Zapp. For detailed information about the expected request and response formats for each API endpoint, please refer to the Mobile Login and the TV Login guides.

The Login Endpoint expects a POST request with the following JSON body:

{ "email": "<USER_EMAIL>", "password": "<USER_PASSWORD>" }

A successful response for the Login endpoint returns a JSON object with a status code of 200.

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "expires_in": <EXPIRES_IN_SECONDS>
}

The JSON object contains the following keys:

access_token: A unique token representing the user's authenticated session. Store and use this token for subsequent authenticated requests.
refresh_token: A unique token used to request a new access_token when the current one expires, providing a seamless user experience.
expires_in: The duration (in seconds) until the access_token expires. Monitor the token's expiration and use the refresh_token to request a new access_token before expiration.

note

Note that for successful responses, the status code should appear both in the status field and in the http status code response.

Unsuccessful Response will return the following JSON body with status code 403:

{
  "formError": "Any global message you want to display to the user",
  "fieldErrors": {
    "email": "A secific error message for the email field. Passing true instead of a string will mark the field with an error border",
    "password": "A specific error message for the password field. Passing true instead of a string will mark the field with an error border"
  }
}

Register URL

The Register URL expectes a POST request with the following JSON body:

{
 "firstName": "<FIRST_NAME>",
 "lastName": "<LAST_NAME>",
 "email": "<EMAIL>",
 "password": "<PASSWORD>",
 "approveTermsOfUse": "on" or null,
 "approveMarketing": "on" or null
}

A successful response for the Login endpoint returns a JSON object with a status code of 200.

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "expires_in": <EXPIRES_IN_SECONDS>
}

The JSON object contains the following keys:

access_token: A unique token representing the user's authenticated session. Store and use this token for subsequent authenticated requests.
refresh_token: A unique token used to request a new access_token when the current one expires, providing a seamless user experience.
expires_in: The duration (in seconds) until the access_token expires. Monitor the token's expiration and use the refresh_token to request a new access_token before expiration.

An unsuccessful Response will return the following JSON body with status code 403:

{
  "formError": "Any global message you want to display to the user",
  "fieldErrors": {
    "email": "A specific error message for the email field'. Passing true instead of a string will mark the field with an error border",
    "password": "A specific error message for the password field.  Passing true instead of a string will mark the field with an error border",
    "firstName": "A specific error message for the first name field.  Passing true instead of a string will mark the field with an error border",
    "lastName": "A specific error message for the last name field.  Passing true instead of a string will mark the field with an error border",
    "email": "A specific error message for the email field.  Passing true instead of a string will mark the field with an error border",
    "password": "A specific error message for the password field.  Passing true instead of a string will mark the field with an error border",
    "approveTermsOfUse": "A specific error message for the terms of use field.  Passing true instead of a string will mark the field with an error border",
    "approveMarketing": "A specific error message for the marketing field.  Passing true instead of a string will mark the field with an error border"
  }
}

Refresh Token URL

note

The app will use the refresh_token it obtained in the login/register response. to periodically check if the user is still authorized.

The Refresh URL expects POST request with the following JSON body:

{
  "refresh_token": "<REFRESH_TOKEN>"
}

A successful response for the Login endpoint returns a JSON object with a status code of 200.

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "expires_in": <EXPIRES_IN_SECONDS>
}

The JSON object contains the following keys:

access_token: A unique token representing the user's authenticated session. Store and use this token for subsequent authenticated requests.
refresh_token: A unique token used to request a new access_token when the current one expires, providing a seamless user experience.
expires_in: The duration (in seconds) until the access_token expires. Monitor the token's expiration and use the refresh_token to request a new access_token before expiration.

An unsuccessful Response will return the following JSON body with status code 403.

Reset Password URL

The reset password URL expects a POST request with the following JSON body:

{
  "email": "<USER_EMAIL>"
}

A Successful Response should return a response with status code 200 or 201

note

Resting passwords should be done in the browser, outside of the app. It's your responsibility to send a reset password email to the user and to implement all the reset password flow on the web.

An unsuccessful Response will return the following JSON body with status code 403:

{
  "formError": "Any global message you want to display to the user",
  "fieldErrors": {
    "email": "A specific error message for the email field'. Passing true instead of a string will mark the field with an error border"
  }
}

Delete Account URL

The Delete Account URL expects POST request with the user's token as a context key:

Your server will get a query param called ctx
When base64 decoding the ctx value you'll get a JSON object with the following keys:
- quick-brick-login-flow.access_token (for mobile)
- zapp_login_plugin_oauth_tv_2_0.access_token (for TVs)

Depending if the request is coming form mobile or TV one of those keys will hold the user's token - use the token to identify the user and delete its account.

info

A common way to identify the user from the access token is to use JWT as the access token and decode it to get the user id.

A successful delete account api should return a successful 200 response.
An unsuccessful Response will return an error with status code >=400.

Implementing the API Endpoints​

Login URL​

Register URL​

Refresh Token URL​

Reset Password URL​

Delete Account URL​

Implementing the API Endpoints

Login URL

Register URL

Refresh Token URL

Reset Password URL

Delete Account URL