Authentication

Overview

Authentication in GlobalTV Roku is credential-based. The user enters a username and password on the LoginScreen, and AuthTask calls the backend to validate them. On success, credentials are saved to the Roku Registry and used for auto-login on the next launch. A background session check re-authenticates at a fixed interval while the app is running.

AuthTask

Background task that performs the HTTP auth request and writes result fields

RegistryManager

Persists and retrieves credentials under the GlobalTV registry section

LoginScreen

Captures username and password using Roku’s on-device keyboard dialog

GTV_AuthClassifyFailure

Classifies every auth failure into one of five reason codes

Auth flow

User enters credentials

LoginScreen opens a StandardKeyboardDialog for the username field, then another for the password field. On submit, it calls TryLogin(), which first requests the Roku email via ChannelStore.getUserData (RFI), then starts AuthTask.

Server resolution

AuthTask calls GTV_ResolveServerForAuth(), which iterates the server probe list — LAN servers first, then the public WAN server — using health-check pings. The first server that responds becomes the active server for this session and is saved to the Registry (lastServer key).

Auth HTTP request

AuthTask issues a GET to the auth endpoint with URL-encoded credentials:

authUrl = server + "/auth/" + encUser + "/" + encPass
resp = GTV_HttpGet(authUrl, c.TIMEOUT_AUTH)

The endpoint pattern (from AppConstants.PATH_AUTH_TPL) is:

/auth/{user}/{pass}

Response parsing

On HTTP 2xx, the task parses the JSON body and checks the subscriberStatus, subscriber_active, or active fields to confirm the subscriber is active. If any field signals an inactive account, the task classifies the failure and exits without saving credentials.

Success: credentials saved

On a fully successful auth, AuthTask saves credentials to the Registry and sets global state:

GTV_RegSaveCredentials(username, password)  ' saves username + password keys
m.global.activeServer     = server
m.global.isAuthenticated  = true
m.global.subscriberActive = true

LoginScreen receives result

LoginScreen observes AuthTask.done. On success, it emits loginSucceeded = true with loginResult (username, password, rokuEmail). MainScene handles the rest of the launch sequence.

Auth endpoint

The endpoint template is defined in AppConstants as PATH_AUTH_TPL:

PATH_AUTH_TPL : "/auth/{user}/{pass}"

At runtime, AuthTask builds the URL by URL-encoding both values:

encUser = GTV_UrlEncode(username)
encPass = GTV_UrlEncode(password)
authUrl = server + "/auth/" + encUser + "/" + encPass

On every app launch, MainScene checks whether credentials exist in the Registry before showing the LoginScreen:

' RegistryManager.brs
function GTV_RegHasCredentials() as Boolean
    c = AppConstants()
    u = GTV_RegRead(c.REG_KEY_USER)
    p = GTV_RegRead(c.REG_KEY_PASS)
    return (u <> "" and p <> "")
end function

function GTV_RegLoadCredentials() as Object
    c = AppConstants()
    u = GTV_RegRead(c.REG_KEY_USER)
    p = GTV_RegRead(c.REG_KEY_PASS)
    if u = "" or p = ""
        return invalid
    end if
    return {username: u, password: p}
end function

If credentials are found, MainScene skips the LoginScreen and starts AuthTask directly with the saved values.

Registry keys

All registry values are stored under the GlobalTV section (REG_SECTION = "GlobalTV").

Constant	Key string	Purpose
`REG_KEY_USER`	`username`	Saved username
`REG_KEY_PASS`	`password`	Saved password
`REG_KEY_SERVER`	`lastServer`	Last resolved server URL
`REG_KEY_CHANNEL`	`lastChannelIndex`	Last viewed channel index (for resume)

Session re-auth check

After a successful launch, MainScene runs a periodic re-auth check to detect expired or revoked sessions while the app is in use.

SESSION_AUTH_CHECK_MS : 420000   ' 7 minutes

If re-auth fails with a credential or inactive reason code, the user is sent back to the LoginScreen with a pre-populated error notice.

Timeouts and retries

Constant	Value	Description
`TIMEOUT_AUTH`	`15000` ms	Maximum wait time for the auth HTTP response
`TIMEOUT_HTTP`	`12000` ms	General HTTP timeout used for non-auth requests
`TIMEOUT_HEALTH`	`2500` ms	Server ping timeout during server resolution
`RETRY_MAX`	`3`	Maximum retry attempts for network-level failures
`SERVER_LAN_FORCE_RETRIES`	`3`	Number of LAN probe retries before failing over to WAN

The LoginScreen also arms a guard timer to cancel a hung auth attempt. The guard duration is computed as:

function GTV_LoginGuardDurationSeconds() as Integer
    c = AppConstants()
    totalMs = (c.TIMEOUT_HEALTH * (c.SERVER_LAN_FORCE_RETRIES + 1)) + c.TIMEOUT_AUTH + 5000
    if totalMs < 20000 then totalMs = 20000
    return Int((totalMs + 999) / 1000)
end function

Failure classification

GTV_AuthClassifyFailure maps every auth error to one of five integer reason codes. Both AuthTask and PlaylistTask call this function to decide how to present errors to the user and whether to clear credentials.

Reason codes

Constant	Value	Meaning
`AUTH_REASON_NONE`	`0`	No failure — auth succeeded
`AUTH_REASON_NETWORK_DOWN`	`460`	Network unavailable or HTTP timeout (`code = -1`)
`AUTH_REASON_CREDENTIALS`	`401`	Wrong username or password
`AUTH_REASON_INACTIVE`	`470`	Account exists but subscriber is inactive
`AUTH_REASON_PASSWORD_CHANGED`	`471`	Password was changed or session was revoked

Function signature

function GTV_AuthClassifyFailure(
    httpCode      as Integer,
    reasonText    = invalid as Dynamic,
    bodyText      = invalid as Dynamic,
    subscriberActive = invalid as Dynamic
) as Integer

Parameters:

httpCode — The HTTP response code. -1 immediately returns AUTH_REASON_NETWORK_DOWN.
reasonText — A string hint from the response (e.g. the reason or message field). May be invalid.
bodyText — The raw response body string or parsed object. The function extracts signal text from nested JSON keys (message, reason, error, detail, status, user_inactive_reason, subscriberDisabledReason).
subscriberActive — Boolean hint from a parsed subscriber status field. If explicitly false, returns AUTH_REASON_INACTIVE.

Classification logic

function GTV_AuthClassifyFailure(httpCode as Integer, reasonText = invalid as Dynamic, bodyText = invalid as Dynamic, subscriberActive = invalid as Dynamic) as Integer
    c = AppConstants()

    if httpCode = -1
        return c.AUTH_REASON_NETWORK_DOWN
    end if

    signal = GTV_AuthToText(reasonText)
    signal = GTV_AuthConcatSignal(signal, GTV_AuthToText(bodyText))
    signal = GTV_AuthConcatSignal(signal, GTV_AuthExtractSignalFromBody(bodyText))
    signal = GTV_AuthNormalizeSignal(signal)

    if GTV_AuthLooksInactive(signal, subscriberActive)
        return c.AUTH_REASON_INACTIVE
    end if

    if GTV_AuthLooksCredentialFailure(signal)
        return c.AUTH_REASON_CREDENTIALS
    end if

    if GTV_AuthLooksPasswordChanged(signal)
        return c.AUTH_REASON_PASSWORD_CHANGED
    end if

    if httpCode = 401 or httpCode = 403 or httpCode = 404
        return c.AUTH_REASON_CREDENTIALS
    end if

    return c.AUTH_REASON_NONE
end function

Signal text is Unicode-normalized (accented characters stripped) and lowercased before pattern matching, so Spanish and English error messages from the backend are handled identically.

How `LoginScreen` reacts to each code

Code	UI behavior
`AUTH_REASON_CREDENTIALS`	Clears the password field, focuses password input, shows error message
`AUTH_REASON_PASSWORD_CHANGED`	Clears the password field, focuses password input, shows error message
`AUTH_REASON_INACTIVE`	Clears the password field, focuses the login button, shows error message
`AUTH_REASON_NETWORK_DOWN`	Shows the server timeout error, focuses the login button
`AUTH_REASON_NONE` (unexpected)	Shows generic error, focuses the login button

Get Started

Architecture

Core Features

Configuration

Build & Deploy

Reference

Overview

AuthTask

RegistryManager

LoginScreen

GTV_AuthClassifyFailure

Auth flow

Auth endpoint

Registry keys

Session re-auth check

Timeouts and retries

Failure classification

Reason codes

Function signature

Classification logic

How `LoginScreen` reacts to each code

​Overview

AuthTask

RegistryManager

LoginScreen

GTV_AuthClassifyFailure

​Auth flow

​Auth endpoint

​Auto-login

​Registry keys

​Session re-auth check

​Timeouts and retries

​Failure classification

​Reason codes

​Function signature

​Classification logic

​How LoginScreen reacts to each code

Overview

Auth flow

Auth endpoint

Auto-login

Registry keys

Session re-auth check

Timeouts and retries

Failure classification

Reason codes

Function signature

Classification logic

How `LoginScreen` reacts to each code