Documentation - OTP Pro

Login Form

Renders a login form with OTP Pro support. This tag is designed to support multi-step login flows where the member may need to enter an OTP code (or follow a magic link) after submitting their username/password.

Syntax + Examples

{exp:jcogs_otp_pro:login_form return="/account"}

Syntax

Parameters

return – redirect URL after successful login (optional)
otp_return – redirect URL for OTP validation page (Pattern 2 flow; optional)
form_id – HTML id attribute for the form (default: otp_login_form)
form_class – HTML class attribute for the form (default: otp-login-form)
error_handling – currently reserved (default: inline)
auto_load_assets – yes/no; auto-includes the OTP Pro stylesheet from the theme folder (default: yes)

Syntax

Variables

form_open, form_close – the opening/closing form HTML
return_input, otp_return_input – hidden inputs for redirects
show_otp – whether the OTP step is currently being shown (set from flashdata)
username, username_readonly, password_readonly, username_required, password_required
requires_code_delivery – true if the selected transport requires sending a code
resend_action_url – URL to trigger a resend (when supported)
delivery_method, transport_id, payload_id, provider_name
is_locked_out, attempts_remaining, lockout_minutes_remaining, lockout_message, warning_message, otp_input_disabled
errors – variable pair containing {error}

Usage Notes

Conditionals

This tag provides a few convenience conditionals by rewriting specific markers in your tagdata. Use these exact conditionals in your template:

{if errors}...{/if}
{if show_otp}...{/if}
{if is_locked_out}...{/if}
{if warning_message}...{/if}

Values:

Example

{exp:jcogs_otp_pro:login_form return="/account"}

    {if errors}
        <div class="alert alert-danger">
            {errors}<p>{error}</p>{/errors}
        </div>
    {/if}

    {form_open}
        {return_input}

        <label>Username</label>
        <input type="text" name="username" value="{username}" {username_readonly} {username_required}>

        <label>Password</label>
        <input type="password" name="password" {password_readonly} {password_required}>

        {if show_otp}
            <label>OTP code</label>
            <input type="text" name="otp_code" maxlength="6" inputmode="numeric" {otp_input_disabled}>

            {if requires_code_delivery}
                <p>We sent a code via {provider_name}.</p>
                <p><a href="{resend_action_url}">Resend code</a></p>
            {/if}
        {/if}

        <button type="submit">Sign in</button>
    {form_close}

{/exp:jcogs_otp_pro:login_form}

Setup Form

Renders the OTP setup form (for initial configuration). This tag supports authenticator-based setup (QR code + secret) and delivery-based setup (for example email), including optional backup code display.

Syntax + Examples

This tag posts to the OTP Pro setup action. Use a hidden return input inside the form (as in the sample templates) to control where the member is redirected.

Values:

Example

{exp:jcogs_otp_pro:setup_form show_backup_codes="yes"}
    {if ee_mfa_enabled}
        <div class="alert alert-warning">
            <h3>{warning_title}</h3>
            <p>{warning_message}</p>
        </div>
    {/if}
    {if already_setup}
        <p>{message}</p>
    {if:else}
        {if display_backup_codes == 'yes'}
            <h3>Backup codes</h3>
            {backup_codes}{code}{/backup_codes}
        {if:else}
            {if errors}
                <div class="alert alert-danger">{errors}<p>{error}</p>{/errors}</div>
            {/if}
            {form_open}
                <input type="hidden" name="return" value="/account">
                {if qr_code}
                    <img src="{qr_code}" alt="QR code">
                    <p>Secret: <code>{secret}</code></p>
                {/if}
                <label>Verification code</label>
                <input type="text" name="test_code" maxlength="6" inputmode="numeric" required>
                <button type="submit">Enable OTP</button>
            {form_close}
        {/if}
    {/if}
{/exp:jcogs_otp_pro:setup_form}

Status

Outputs the current member’s OTP status and key configuration values. This is typically used to show “enabled/disabled” state, the current delivery channel, and recent activity.

Syntax + Examples

{exp:jcogs_otp_pro:status}

Syntax

Variables

otp_enabled – y/n
otp_setup_completed – y/n
delivery_method – legacy delivery channel string
delivery_method_name, delivery_method_display
transport_id, payload_id
enabled_date, enabled_timestamp
last_validated, last_validated_formatted, last_validated_relative
backup_codes_count, has_backup_codes, backup_code_available
trusted_device_count
can_enable – y/n

Values:

Example

{exp:jcogs_otp_pro:status}
    {if otp_enabled == 'y'}
        <p>OTP enabled via {delivery_method_name}.</p>
        <p>Last validated: {last_validated_relative}</p>
    {if:else}
        <p>OTP is not enabled.</p>
    {/if}
{/exp:jcogs_otp_pro:status}

Delivery Methods

Lists available delivery channels for the logged-in member and provides a ready-made form for switching.

Syntax + Examples

{exp:jcogs_otp_pro:delivery_methods}

Syntax

Variables

current_method – legacy delivery channel string
current_transport_id, current_payload_id
current_method_name
providers – variable pair with:
{providers} fields: identifier, transport_id, payload_id, name, description, is_current, can_change_to, plus form helpers form_open, form_close, method_input, transport_input, payload_input
errors – variable pair containing {error}
success – success message string (flashdata)

Values:

Example

{exp:jcogs_otp_pro:delivery_methods}

    {if success}<div class="alert alert-success">{success}</div>{/if}
    {if errors}<div class="alert alert-danger">{errors}<p>{error}</p>{/errors}</div>{/if}

    <ul>
    {providers}
        <li>
            <strong>{name}</strong>
            {if is_current}<em>(current)</em>{/if}
            {if can_change_to}
                {form_open}{method_input}{transport_input}{payload_input}
                    <button type="submit">Switch</button>
                {form_close}
            {/if}
        </li>
    {/providers}
    </ul>

{/exp:jcogs_otp_pro:delivery_methods}

Trusted Devices

Lists trusted devices and supports revocation.

Syntax + Examples

{exp:jcogs_otp_pro:trusted_devices}

Syntax

Variables

total_count, has_devices
revoke_all_url and revoke_all_form_open/revoke_all_form_close/revoke_all_input
devices – variable pair with:
{devices} fields: device_id, device_name, trusted_at, trusted_at_formatted, expires_at, expires_at_formatted, last_used, last_used_formatted, ip_address, user_agent, is_current_device, can_revoke, plus revoke helpers revoke_url, revoke_form_open, revoke_form_close, device_id_input
errors – variable pair containing {error}
success – success message string (flashdata)

Values:

Example

{exp:jcogs_otp_pro:trusted_devices}
    <ul>
    {devices}
        <li>
            {device_name} (last used: {last_used_formatted})
            {if can_revoke == 'y'}
                {revoke_form_open}{device_id_input}
                    <button type="submit">Revoke</button>
                {revoke_form_close}
            {/if}
        </li>
    {/devices}
    </ul>
{/exp:jcogs_otp_pro:trusted_devices}

Disable Form

Renders a form for members to disable OTP (where permitted).

Syntax + Examples

{exp:jcogs_otp_pro:disable_form}

Syntax

Variables

form_open, form_close
require_password, show_warning
member_email
enabled_since
trusted_device_count
errors – variable pair containing {error}

Values:

Example

{exp:jcogs_otp_pro:disable_form require_password="y" show_warning="y"}

    {if errors}<div class="alert alert-danger">{errors}<p>{error}</p>{/errors}</div>{/if}

    {form_open}
        <input type="hidden" name="return" value="/account/security">

        {if show_warning}
            <div class="alert alert-warning">
                Disabling OTP reduces account security.
            </div>
        {/if}

        {if require_password}
            <label>Password</label>
            <input type="password" name="password" required>
        {/if}

        <button type="submit">Disable OTP</button>
    {form_close}

{/exp:jcogs_otp_pro:disable_form}

Dialog

Displays the OTP validation dialog when OTP validation is required. This is primarily intended for flows where the member is already logged in but must validate OTP before continuing.

Syntax + Examples

{exp:jcogs_otp_pro:dialog}...{/exp:jcogs_otp_pro:dialog}

Syntax

Parameters:

return – URL to redirect to after validation (optional; may also be provided as a GET parameter)

Usage Notes

If the member is not logged in, this tag outputs nothing.
If OTP is not enabled for the member, this tag outputs nothing.
If OTP is already validated and a return URL is present, the tag redirects.

Action URL

Outputs an action URL for JCOGS OTP Pro actions (useful for custom forms and AJAX requests).

Syntax + Examples

{exp:jcogs_otp_pro:action_url action="..."}

Syntax

Parameters

action – the action name to generate a URL for (required)

Supported actions

login
validate
setup
disable
change_delivery
revoke_device

Values:

Example

<form method="post" action="{exp:jcogs_otp_pro:action_url action='disable'}">
    <input type="hidden" name="return" value="/account/security">
    <button type="submit">Disable OTP</button>
</form>

Get Error

Outputs the most recent OTP Pro error message (for example, after redirects).

Syntax + Examples

{exp:jcogs_otp_pro:get_error}

Syntax

Usage

As a tag pair: exposes {error} and {has_error}
As a single variable: {exp:jcogs_otp_pro:get_error:error}

Values:

Example

{exp:jcogs_otp_pro:get_error}
    {if has_error}
        <div class="alert alert-danger">{error}</div>
    {/if}
{/exp:jcogs_otp_pro:get_error}

Ajax Login Inline

Implements an AJAX login flow with inline progressive reveal UX.

Syntax + Examples

{exp:jcogs_otp_pro:ajax_login_inline return="/account"}

Syntax

Parameters

return – URL to redirect after successful login (default: site URL)
form_id – login form ID (default: otp-ajax-login-inline)
form_class – additional CSS classes (default: otp-form)
show_remember_device – yes/no (default: yes)
show_remember_login – yes/no (default: yes)
show_backup_codes – yes/no (default: yes)
auto_load_assets – yes/no (default: yes)

Usage Notes

This tag outputs a self-contained HTML/JS login experience (it does not parse tagdata).
It expects the OTP Pro theme assets to be available at themes/user/jcogs_otp_pro/.

Ajax Login Modal

Implements an AJAX login flow with modal dialog UX.

Syntax + Examples

{exp:jcogs_otp_pro:ajax_login_modal return="/account" modal_title="Two-Factor Authentication"}

Syntax

Parameters

return – URL to redirect after successful login (default: site URL)
form_id – login form ID (default: otp-ajax-login-modal)
form_class – additional CSS classes (default: otp-form)
show_remember_device – yes/no (default: yes)
show_remember_login – yes/no (default: yes)
show_backup_codes – yes/no (default: yes)
modal_title – modal heading text (default: Two-Factor Authentication)
auto_load_assets – yes/no (default: yes)

Usage Notes

This tag outputs a self-contained HTML/JS login experience (it does not parse tagdata).
Magic link payloads are handled by switching the modal into a “check your email” state.