Purpose

The purpose of logging in is to perform authentication using the customer credentials once for a given application (except in cases of a factory reset) to secure a token that can be used for all subsequent API calls.

The advantages of a token over email address and password is that the user can revoke the token at will in the event of a compromised, lost or stolen device without losing control of their password.

Procedure

Each login request consists of a login document (See login) that contains a member record and (in the case of a TV Recorder a device record).

There are two cases when it comes to user login, new users and existing users. This detailed flow with example screenshots can be seen at On-Screen Signup.

In both cases we are collecting the minimum amount of information to authenticate an existing user or establish an account for a new user.

NOTE: You are free to submit the login information as a POST or PUT, using a POST will result in the response containing a “Location” header that points to the newly created member record, in both cases the response will also contain the full details for the submitted member (and any associated device record).

For both classes of user the login request must contain the email address and password (and for a TV Recorder the device uid and label).

For new users the login request must also contain the region id.

The response from the login request contains a token that is required for all subsequent API calls, calls must contain the parameters email_address and token on the URL in order for the call to succeed.