Users – EiTV CLOUD | API Documentation

Following, we have all information related to users management, like creating or editing an user, and many others operations.

Login / Logout

First, we describe how to login an user into your instance

method: POST
URL: /sessions.json

PARAMETERS:
If Regular User:
{
  "session": {
    "login": "EMAIL",
    "password": "PASSWORD"
  }
}
If Facebook User:
{
  "session": {
    "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
    "provider": "facebook|google"
  }
}
RETURN:
{
  "status": true/false, # status_code 200/401
  "message": "ERROR MESSAGE" # If "status" = false
}

Logout

method: POST
URL: /signout.json

JWT authentication flow

You should always have valid JWT refresh and access tokens. You should store the tokens and their expiration times, e.g., in the browser localStorage.

1. Access token

Example of an access token value:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1aWQiOjEsInR5cCI6ImFjYyIsInZlciI6NCwiZXhwIjoxNjQ1MjgyNDI0fQ.9C9gPWiV4qQks7fa4wPs6gCkaOi4qJPzcol2j9nFWEs

1.1. If you don’t have an access token or the access token has expired

You need to generate an access token. See Item 1.3.

1.2. If you already have an access token

Use the access_token in the Authorization header in every request that needs authorization.

Example of a Bearer token authorization header:

headers['Authorization'] = 'Bearer {access_token}'

If you get status code 401, you need to update the access token. See Item 1.3.

Below is an example of a response for an unauthorized request:

– Status code: 401
– Body:

RESPONSE:
{
  "error": "Not Authorized"
}

1.3. Generating an access token

1.3.1. If you don’t have a refresh token or the refresh token has expired

You need to generate a refresh token. See Item 2.1.

1.3.2. If you already have an refresh token

method: POST
URL: /api_update_token.json
Headers:
‘Authorization’: ‘Bearer {refresh_token}’

If the refresh token is valid, the response should be:

– Status code: 200
– Body:

RESPONSE:
{
  "access_token": "{access_token}",
  "access_token_expiration": "YYYY-MM-ddTHH:mm:ss.SSSZ",
  "user": "{user_id}-{user_name}"
}

In case of failure:

– Status code: 401
– Body:

RESPONSE:
{
  "error": true
}

You need to update the refresh token. See Item 2.1.

2. Refresh token

Example of a refresh token value:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1aWQiOjEsInR5cCI6InJlZiIsInZlciI6NCwiZXhwIjoxNjYwODM0NDI0fQ.8myc8tz0gUU-gRg8fx6gmvjWFydi1T_MzYt1pq-aQe4

2.1. Generating/updating the refresh token

method: POST
URL: /api_authenticate.json

– Parameters:
‘email={email}&password={password}’
or
‘key={KEY}&hardware_id={hardware_id}&device_type={device_type}’

Valid device types: [“androidbox”, “androidtv”, “appletv”, “firetv”, “lgtv”, “roku”, “samsungtv”]

In case of success:
– Status code: 200
– Body:

RESPONSE:
{
  "refresh_token": "{refresh_token}",
  "refresh_token_expiration": "YYYY-MM-ddTHH:mm:ss.SSSZ",
  "access_token": "{access_token}",
  "access_token_expiration": "YYYY-MM-ddTHH:mm:ss.SSSZ",
  "user": "{user_id}-{user_name}"
}

In case of failure:
– Status code: 401
– Body:

RESPONSE:
{
  "error": true
}

3. Logout

The app should manage the device logout. For example, it can delete the current refresh and access tokens. This way, if the tokens don’t exist, the user should not be considered logged in.

If you need to destroy other sessions (i.e., invalidate the tokens of everyone that is using the same user account regardless of the tokens being used) or if you need to deactivate the previously enabled device:

method: POST
URL: /api_signout.json
Headers:
‘Authorization’: ‘Bearer {refresh_token}’

Parameters:
– [optional] ‘revoke_token=1’ to invalidate all the current user tokens
– [optional] ‘hardware_id={hardware_id}&device_type={device_type}’ to deactivate the device
– [optional] ‘update_token=1’ to obtain new valid tokens

In case of success:

– Status code: 200
– Body:

RESPONSE:
{
  "user": "{user_id}-{user_name}",
  "refresh_token": "{refresh_token}",
  "refresh_token_expiration": "YYYY-MM-ddTHH:mm:ss.SSSZ",
  "access_token": "{access_token}",
  "access_token_expiration": "YYYY-MM-ddTHH:mm:ss.SSSZ"
}

In case of failure:

– Status code: 401
– Body:

RESPONSE:
{
  "error": true
}

New Regular User

Next, you can follow 3 steps to create a new user:

1) Request Form (with possible Custom Fields)

method: GET
URL: /management/users/new.json

PARAMETERS:
RETURN:
{
  "user": {
    "id": null,
    "name": null,
    "email": null,
    "language": "LANGUAGE", # "en","pt","es"
    "properties": [ # If exist custom fields
      {
        "id": null,
        "custom_field_id": ID,
        "value": null
      }
    ]
  },
  "custom_fields": [ # If exist custom fields
    {
      "id": ID,
      "name": "NAME",
      "field_name": {
        "en": "FIELD NAME IN ENGLISH",
        "pt": "FIELD NAME IN PORTUGUESE"
      },
      "field_type": "FIELD TYPE", # "text_box","date_picker","check_box","radio_button","combo_box"
      "field_values": [ # If "field_type" = "check_box","radio_button","combo_box"
        {
          "en": "OPTION VALUE IN ENGLISH",
          "pt": "OPTION VALUE IN PORTUGUESE",
          “parent_value”: “PARENT'S VALUE POSITION”
        }
      ],
      "required": true/false,
      "model_name": "User",
      “parent_id”: ID # Parent's ID
    }
  ]
}

2) Submit Form (with possible Custom Fields) # Show terms

method: POST
URL: /management/users.json

PARAMETERS:
{
  "user": {
    "name": "NAME",
    "email": "EMAIL",
    "email_confirmation": "EMAIL",
    "password": "PASSWORD",
    "password_confirmation": "PASSWORD",
    "permission": "user",
    "language": "LANGUAGE", # "en","pt","es"
    "user_file": "IMAGE",
    "properties_attributes": { # If exist custom fields
      "INDEX": { # 0,1,2,...
        "custom_field_id": "ID"
        "value": "POSITION", # "check_box" = “” or “|1|” or "|1||2|" or ..., "radio_button","combo_box" = "1" or "2" or ..., "date_picker" = "yyyy-mm-dd"
      }
    }
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "errors": { # caso "status" = false
    "user": {
      "FIELD": [ # "name","email","password","properties.value"
        "ERROR MESSAGE"
      ],
      "properties": [ # If exist custom fields
        {
          "custom_field_id": ID,
          "errors": {
            "value": [
              "ERROR MESSAGE"
            ]
          }
        }
      ]
    }
  }
}

3) Email verification

method: PUT
URL: /email_verifies/ID.json # ID = 4 digit code sent by email

PARAMETERS:
{
  "user": {
    "password": "PASSWORD",
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400,401
  "error": "ERROR MESSAGE" # If "status" = false
}

Facebook User

EITV CLoud allows using Facebook as a source for user information sharing, like name and email. Using this feature a instance can create and login users using their Facebook credentials, with no password need for EiTV Cloud.

Following, we have all documentation for integration.

First, we check if there are an user with a given Facebook Token and check if Custom Fields are enabled

method: GET
URL: /sessions/new.json

PARAMETERS:
{
  "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
  "provider": "facebook|google"
}
RETURN:
{
  "user":true/false,
  "custom_fields":true/false
}

Create New User if Custom Fields are disabled

method: POST
URL: /sessions.json

PARAMETERS:
{
  "session": {
    "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
    "provider": "facebook|google"
  }
}
RETURN:
{
  "status": true/false, # status_code 200/401
  "message": "ERROR MESSAGE" # If "status" = false
}

New Facebook User with Custom Fields

1) Request a form with Custom Fields

method: GET
URL: /management/users/new.json

PARAMETERS:
RETURN:
{
  "user": {
    "id": null,
    "name": null,
    "email": null,
    "language": "LANGUAGE", # "en","pt","es"
    "properties": [ # Custom Fileds
        {
          "id": null,
          "custom_field_id": ID,
          "value": null
        }
    ]
  },
  "custom_fields": [ # Custom Fileds
    {
      "id": ID,
      "name": "NOME",
      "field_name": {
        "en": "FIELD NAME IN ENGLISH",
        "pt": "FIELD NAME IN PORTUGUESE"
      },
      "field_type": "FIELD TYPE", # "text_box","date_picker","check_box","radio_button","combo_box"
      "field_values": [ # If "field_type" = "check_box","radio_button","combo_box"
        {
          "en": "OPTION VALUE IN ENGLISH",
          "pt": "OPTION VALUE IN PORTUGUESE",
          “parent_value”: “PARENT'S VALUE POSITION”
        }
      ],
      "required": true/false,
      "model_name": "User",
      “parent_id”: ID # Parent's ID
    }
  ]
}

2) Submit a form with Custom Fields

method: POST
URL: /management/users.json

PARAMETERS:
{
  "user": { # não enviar "name","email","email_confirmation","password","password_confirmation"
    "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
    "provider": "facebook|google"
    "permission": "user",
    "language": "LANGUAGE", # "en","pt","es"
    "properties_attributes": { # Custom fields
      "INDEX": { # 0,1,2,...
        "custom_field_id": "ID"
        "value": "POSITION", # "check_box" = “” or “|1|” or "|1||2|" or ..., "radio_button","combo_box" = "1" or "2" or ..., "date_picker" = "yyyy-mm-dd"
      }
    }
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  # if "status" = true
  "screen": true/false,
  "message": "HTML MESSAGE",
  # if "status" = false
  "errors": { 
    "user": {
      "FIELD": [ # "name","properties.value"
        "ERROR MESSAGE"
      ],
      "properties": [ # Custom fields
        {
          "custom_field_id": ID,
          "errors": {
            "value": [
              "ERROR MESSAGE"
            ]
          }
        }
      ]
    }
  }
}

User Info

Getting User information:

method: GET
URL: /management/users/info.json

PARAMETERS:
RETURN:
{
  "page": "user",
  "user": {
    "id": ”ID", # Format: NUMBER-TEXT
    "name": "NAME",
    "email": "EMAIL",
    "language": "LANGUAGE", # "en","pt","es"
    "thumb_url": "URL",
    "facebook": true/false,
    "permission": "PERMISSION", # "admin", "publisher", "contributor", "user"
    "payment_card_last_4_digits": "NUMBER",
    "email_unsubscribed": true/false,
    "properties":[ # Custom fields
      {
        "id": ID,
        "custom_field_id": ID,
        "value": "POSITION"
      }
    ]
  },
  “channels” : [ # Subscribed channels 
    {
      “CHANNEL ID”
    }
  ],
  # if achievement_enabled (info.json)
  "achievements": [
    {
      "id": ”ID", # Format: NUMBER-TEXT
      "name": "NAME",
      "description": "DESCRIPTION",
      "html_description": "HTML ADDITIONAL DESCRIPTION",
      "points": NUMBER,
      "certificate": true/false,
      "type": "achievement",
      "properties":[ # Custom fields
        {
          "id": ID,
          "custom_field_id": ID,
          "value": "POSITION"
        }
      ]
    }
  ],
  achievements_blocked: [
    ACHIEVEMENT_INFO
  ]
  "achievement_points": NUMBER,
  "achievement_rank": NUMBER
}

Following, we show how to get the user image:

URL: /users/[ID]/retrieve?format=thumb
ID: format NUMBER-TEXT

the achievement thumbnail:

URL: /achievements/[ID]/retrieve?format=thumb
ID: format NUMBER-TEXT

and the user achievement certificate:

URL: /users/[USER_ID]/achievements/[ACHIEVEMENT_ID].pdf
USER_ID: format NUMBER-TEXT
ACHIEVEMENT_ID: format NUMBER-TEXT

Edit User

1) Request Form (with possible custom fields)

method: GET
URL: /management/users/ID/edit.json # User ID on /management/users/info.json

PARAMETERS:
RETURN:
{
  "user": {
    "id": "ID",
    "name": "NAME",
    "email": "EMAIL",
    "language": "LANGUAGE", # "en","pt","es"
    "user_file": "IMAGE", 
    "email_unsubscribed": true/false,
    "properties": [ # If exist custom fields
      {
        "id": "ID", # ID = null, if new custom field
        "custom_field_id": ID,
        "value": "VALUE"
      }
    ]
  },
  "custom_fields": [ # If exist custom fields
    {
      "id": ID,
      "name": "NAME",
      "field_name": {
        "en": "FIELD NAME IN ENGLISH",
        "pt": "FIELD NAME IN PORTUGUESE"
      },
      "field_type": "FIELD TYPE", # "text_box","date_picker","check_box","radio_button","combo_box"
      "field_values": [ # If "field_type" = "check_box","radio_button","combo_box"
        {
          "en": "OPTION VALUE IN ENGLISH",
          "pt": "OPTION VALUE IN PORTUGUESE",
          “parent_value”: “PARENT'S VALUE POSITION”
        }
      ],
      "required": true/false,
      "model_name": "User",
      “parent_id”: ID # PARENT'S ID
    }
  ]
}

2) Submit Form (with possible custom fields)

method: PUT
URL: /management/users/ID.json

PARAMETERS:
{
  "user": {
    "name": "NAME",
    "email": "EMAIL", # If regular user
    "email_confirmation": "EMAIL", # If regular user
    "password": "PASSWORD", # If regular user and changing password
    "password_confirmation": "PASSWORD", # If regular user and changing password
    "permission": "user",
    "language": "LANGUAGE", # "en","pt","es"
    "properties_attributes": { # If exist custom fields
      "INDEX": { # 0,1,2,...
        "id": "ID" # If NOT a new custom field
        "custom_field_id": "ID"
        "value": "POSITION", # "check_box" = “” or “|1|” or "|1||2|" or ..., "radio_button","combo_box" = "1" or "2" or ..., "date_picker" = "yyyy-mm-dd"
      }
    }
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "errors": { # If "status" = false
    "user": {
      "FIELD": [ # "name","email","password","properties.value"
        "ERROR MESSAGE"
      ],
      "properties": [ # If exist custom fields
        {
          "custom_field_id": ID,
          "errors": {
            "value": [
              "ERROR MESSAGE"
            ]
          }
        }
      ]
    }
  }
}

Remove User

method: POST
URL: /management/users/ID/remove.json

PARAMETERS:
{
  "user": {
    "password": "PASSWORD", # If regular user (not Facebook user)
  }
}
RETURN:
{
  "status": true/false, # status_code 200/401
  "message": "ERROR MESSAGE" # If "status" = false
}

Reset Password

To reset an user password, you need to perform the following call:

method: POST
URL: /password_resets.json

PARAMETERS:
{
  “password_reset”: {
    “email”:  "EMAIL"
  }
}
RETURN:
{
  "status": TRUE
}

Resend Verification Code

To resend the verification code, you need to perform the following call:

method: POST
URL: /email_verifies.json

PARAMETERS:
{
  “email_verify”: {
    “email”:  "EMAIL"
  }
}
RETURN:
{
  "status": TRUE
}

Subscriptions

Showing all subscriptions for an User:

method: GET
URL: /management/users/ID/subscriptions.json # User ID on /management/users/info.json

PARAMETERS:
{
  “subscription_page”: “NUMBER” # Pagination, starting on 1
}
RETURN:
{
  "page": "subscriptions",
  "subscriptions": [
    {
      "SUBSCRIPTION INFORMATION"
    }
  ],
  "pagination": {
    "current": “NUMBER”, # Current page
    "last": true/false # Last page
  }
}

Showing a subscription for an User with Subscription ID:

method: GET
URL: /management/users/ID/subscriptions/ID/edit.json # User ID on /management/users/info.json and Subscription ID on /management/users/ID/subscriptions.json

PARAMETERS:
RETURN:
{
  "page": "subscription",
  "subscription": [
    {
      "id": "ID", # NUMBER-TEXT
      "user_group_id": "SUBSCRIPTION PLAN ID", # NUMBER-TEXT (deprecated)
      "subscriptable_id": "SUBSCRIPTION PLAN ID", # NUMBER-TEXT
      "subscriptable_type": "UserGroup",
      "name": "NAME",
      "duration": "DURATION", # ["monthly"|"quarterly"|"triannually"|"semiannual"|"annual"|"biennial"|"perpetual"]
      "recurrent": true/false,
      "payment_method": "PAYMENT METHOD", # [“card”|”boleto”]
      "status": "PAYMENT STATUS", # [“trial”|“paid”|”pending”|”canceled”|”expired”]
      "current_period_start": “PAYMENT CYCLE START”, # yyyy-mm-dd
      "current_period_end": “PAYMENT CYCLE END”, # yyyy-mm-dd
      "suspended": true/false
      "price": “PRICE”, # In cents
      "installments": NUMBER, 
      "card_last_digits": “CARD LAST 4 DIGITS”, # If payment_method = “card”
      "invoice_url": "INVOICE URL", # If payment_method = “boleto”
      "invoice_expires_at": "INVOICE EXPIRES" # yyyy-mm-dd, if payment_method = “boleto”,
      "invoices": [
        {
          "date": "DATE", # yyyy-mm-dd
          "value": "VALUE", # In cents          
          "status": "STATUS", # [“paid”|”pending”|”expired”]
          "errors": {
            "code": "CODE",
            "date": "DATE",
            "text": "TEXT"
          }
        }
      ],
      "coupon": "COUPON INFO",
      "trial_days": NUMBER
    }
  ],
}

Next you have the request to change a credit card used on a subscription using the User ID

method: PUT
URL: /management/users/ID/subscriptions/ID.json # User ID on /management/users/info.json

PARAMETERS:
{
  “card_token”: “TOKEN” 
}
RETURN:
{
  "status": true/false, # status_code 200/400
}

Here you can see how to cancel a subscription using the User ID

method: DELETE
URL: /management/users/ID/subscriptions/ID.json # User ID on /management/users/info.json

PARAMETERS:
{
  "subscription": {
    "password": "PASSWORD",
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "error": "ERROR MESSAGE" # If "status" = false
}

To reactivate a subscription before the expiration date:

method: POST
URL: /management/users/ID/subscriptions/ID/reactivate.json # User ID on /management/users/info.json

RETURN:
{
  "status": true/false, # status_code 200/400
}

TVODs

Showing all TVODs for an User:

method: GET
URL: /management/users/ID/tvods.json # User ID on /management/users/info.json

PARAMETERS:
{
  “tvod_page”: “NUMBER” # Pagination, starting on 1
}
RETURN:
{
  "page": "tvods",
  "tvods": [
    {
      "TVOD INFORMATION"
    }
  ],
  "pagination": {
    "current": “NUMBER”, # Current page
    "last": true/false # Last page
  }
}

Showing a TVOD for an User with TVOD ID:

method: GET
URL: /management/users/ID/tvods/ID.json # User ID on /management/users/info.json and TVOD ID on /management/users/ID/tvods.json

PARAMETERS:
RETURN:
{
  "page": "tvod",
  "tvod": [
    {
      "id": "ID", # NUMBER-TEXT
      "subscriptable_id": "TVOD ID", # NUMBER-TEXT
      "subscriptable_type": "Video|Audio",
      "name": "NAME",
      "duration": "DURATION", # ["purchase"|"rental"]
      "recurrent": true/false,
      "payment_method": "PAYMENT METHOD", # [“card”|”boleto”]
      "status": "PAYMENT STATUS", # [“paid”|”pending”|”expired”]
      "current_period_start": “PAYMENT CYCLE START”, # yyyy-mm-dd
      "current_period_end": “PAYMENT CYCLE END”, # yyyy-mm-dd
      "price": “PRICE”, # In cents
      "installments": NUMBER, 
      "card_last_digits": “CARD LAST 4 DIGITS”, # If payment_method = “card”
      "invoice_url": "INVOICE URL", # If payment_method = “boleto”
      "invoice_expires_at": "INVOICE EXPIRES" # yyyy-mm-dd, if payment_method = “boleto”,
      "invoices": [
        {
          "date": "DATE", # yyyy-mm-dd
          "value": "VALUE", # In cents
          "status": "STATUS", # [“paid”|”pending”|”expired”]
        }
      ]
    }
  ],
}

Leaderboards

method: GET
URL: /achievements/leaderboards.json

PARAMETERS:
{
  “user_rank_page”: “NUMBER” # Pagination, starting on 1
}
RETURN:
{
  "page": "leaderboards",
  "user_ranks": [
    {
      "position": NUMBER,
      "name": "NAME",
      "points": NUMBER
    }
  ],
  "pagination": {
    "current": “NUMBER”, # Current page
    "last": true/false # Last page
  }
}

<< Previous topic	Next topic >>