Kwiq icon Kwiq
EN PT ES

Kwiq Auth — Two-Factor Authenticator

Generate TOTP and HOTP codes for your accounts, view SMS and email verification codes, keep secrets in the device keystore, and back up everything with an encrypted envelope.

Table of Contents
  1. What is Kwiq Auth?
  2. Adding an Entry with QR Code
  3. Adding an Entry Manually
  4. SMS and Email Codes
  5. Security and Lock
  6. Backup and Restore
  7. Kwiq Dashboard
  8. MCP Tools (Admin)
  9. Tips and Troubleshooting

What is Kwiq Auth?

Kwiq Auth is the authenticator app built into the Kwiq Launcher. It generates one-time codes for two-factor authentication (2FA) directly on your device, without sending your secrets to any server.

  • TOTP (time-based) codes for services like Google, GitHub, and thousands more that support authenticator apps.
  • HOTP (counter-based) codes for services that use a moving counter.
  • SMS and email verification codes already captured by Kwiq, shown together with your TOTP codes.
  • Secrets are stored encrypted using the Android Keystore, and the app can be protected with a biometric or PIN lock.

Kwiq Auth works with the standard otpauth:// URI format, so you can import accounts from other authenticator apps and export yours to them too.

Adding an Entry with QR Code

The quickest way to add an account is by scanning its QR code:

  1. Open Kwiq Auth from the launcher (or from the Quick Tools) and tap the add button.
  2. Tap "Scan QR Code" and point the camera at the QR code shown by the service when you enable 2FA.
  3. Review the detected issuer, account, and secret, then confirm.

If the QR code is on another screen or a computer, you can scan it directly with the camera or import an image from the gallery.

Adding an Entry Manually

For services that only show the secret text (a Base32 string), add the entry manually:

  1. Tap the add button and choose "Manual Entry".
  2. Fill in the issuer (e.g. "Google"), the account (your email or username), and the secret.
  3. Choose the algorithm: SHA-1 (default) or SHA-256/SHA-512.
  4. Set the digits (usually 6) and, for TOTP, the period (usually 30 seconds).
  5. For HOTP, set the initial counter value instead of the period.

The secret must be a valid Base32 string. Kwiq validates it before saving.

SMS and Email Codes

Many services send the 2FA code by SMS or email. Kwiq already reads these messages and extracts the verification codes:

  • The codes appear in the messages section of the messaging module with the sender and received time.
  • Kwiq Auth shows these codes on the same screen as your TOTP entries, so you have everything in one place.
  • You can copy a code to the clipboard with a single tap.

Reading SMS requires the corresponding permission, granted the first time you use the feature.

Security and Lock

Your secrets never leave the device unencrypted:

  • Each secret is encrypted with AES-GCM using a key stored in the Android Keystore — the same secure hardware-backed storage used by the system.
  • You can enable a lock so the app asks for biometric authentication (fingerprint/face) or the device PIN before showing codes.
  • Codes are only decrypted in memory, on demand, when you view them.

If the device is rooted or compromised, treat your secrets as compromised and rotate them at the services that issued them.

Backup and Restore

Kwiq Auth lets you move your accounts to another device safely:

Encrypted backup

Exports an encrypted envelope (a JSON file protected with a password) containing all your entries. Restore it on a new device with the same password.

otpauth list

Exports a plain-text otpauth:// list that can be imported by other authenticator apps (and imported back into Kwiq).

Import

Restores an encrypted backup or imports an otpauth list. Imports merge with existing entries and skip duplicates.

Kwiq Dashboard

When the Self-Hosted server is active, administrators can also manage codes from the browser:

  • Open the dashboard /auth page to view all TOTP codes (with their remaining time) and see SMS/email codes.
  • Administrators can add new entries, edit, delete, or clear all entries from the browser.
  • Visitors cannot access the auth page.

The dashboard uses the same database as the app, so changes made in one place appear in the other immediately.

MCP Tools (Admin)

AI agents can manage Kwiq Auth through the embedded MCP server. These tools are restricted to administrators:

  • totp_list — lists all entries with id, type, issuer, account, algorithm, digits, period, counter, current code, and remaining seconds.
  • totp_add — adds a new entry (type, issuer, account, secret, algorithm, digits, period, counter).
  • totp_delete — deletes an entry by id.
  • totp_sms_list — lists the active SMS/email verification codes.

If the agent is not authenticated as Admin, the tools return an "Admin access required" error.

Warning MCP auth tools only work when the agent authenticates as an Admin user. Never share your admin token.

Tips and Troubleshooting

A few notes to get the most out of Kwiq Auth:

  • Counter drift: if a HOTP code stops matching, edit the entry and increase the counter.
  • Not supported: Steam (MOTP) and other proprietary formats are not supported.
  • Time sync: TOTP codes depend on the device clock. Keep automatic time enabled.
  • Sharing: never share a backup password or an otpauth list with anyone.