Frequently asked questions
What partners ask when they add Touchque 2FA to their own app: getting started, users and their phones, integration, security.
Getting started
Can I use Touchque instead of Google Authenticator in my own app?
Yes. Touchque replaces the 6-digit code step: after the password, your server calls login.request and the user approves a push in Touchque Authenticator. Your customers link their phone once by scanning a QR you show. Step by step: Add 2FA to your app.
What do I need to start?
An API key from Developers → API keys in the dashboard, a server (Node.js, Python, PHP, Go, .NET, Ruby, Java, or any language over REST) and users with Touchque Authenticator on their phone (iPhone or Android).
Which languages and frameworks are supported?
Server SDKs: Node.js (Express, Next.js), Python (Flask, Django, FastAPI), PHP (Laravel or plain PHP), Go (net/http), .NET (ASP.NET Core), Ruby (Rails) and Java (Spring Boot). In the browser @touchque/web, for React @touchque/react. You can install Node.js (npm), PHP (Composer, from the release tag on GitHub) and Go today; Python, .NET, Ruby and Java are not published yet. The docs home shows each SDK's state.
Do I have to use an SDK?
No. The REST API works from any language; every request is HMAC-SHA256 signed with your API secret. See Authentication and the REST reference.
Can I try it on my own computer?
Yes. The webhook address must be HTTPS in production, but localhost is accepted for local tests, and you can poll the status instead of using a webhook. You need a real phone with Touchque Authenticator to approve.
Your users and their phones
What does the user see on the phone?
Your brand and logo, what is being approved (a sign-in, or details you send such as an amount and a recipient), the city and country from the IP address, and the browser and device from the user agent. There are Approve, Reject and "This wasn't me"; approving asks for Face ID or a fingerprint.
What if the phone has no internet?
You can turn on offline sign: your page shows a QR, the phone reads it without internet and makes a 7-character code, and the user types it into your page. Optionally the app also shows a time-based code that changes every 30 seconds. These codes are lower assurance than a push and are not accepted for critical actions. See Offline sign.
Can my users still type a code?
Only in two cases: the offline codes when the phone has no internet (if you turned them on), and the recovery codes you showed at enrolment when the phone is gone. A normal sign-in has no code, only the push.
Can I import my users’ Google Authenticator accounts?
No. Each user links their phone once with a QR. During the move keep the old code for users who have not linked yet, and delete it for those who have. See Moving users off Google Authenticator.
What happens when a user gets a new phone or loses it?
If they still have the old phone, they move their accounts with the transfer in the app; you do nothing. If the phone is lost, there are recovery codes, moving to a new phone with colleagues vouching, or a reset by you after you have checked who they are. See New or lost phone.
Integration
How long does a sign-in request live?
30 seconds; then its status is EXPIRED and you send a new one. Requests that need longer (for example a person reading an AI agent's request) can ask for up to 300 seconds with expiresIn. An enrolment secret is valid for 5 minutes.
Webhook or status checks?
Both work. The webhook is recommended: you get a signed POST the moment the answer is in. With status checks, ask login.status every 2 seconds for up to 30 seconds. See Callback / webhook and Check status.
What is externalUsername?
The user's id in your system (email, user id, phone). Touchque keeps it only as a reference. Send the same value at enrolment and on every sign-in.
What is number matching?
When the risk is higher, or you ask for requireNumberMatch, the answer carries a challengeCode. You show the number on your page and the user picks the same number on the phone. Nobody can wear a user down with pushes, and users only approve the sign-in they started.
How many pushes can a user get?
At most 5 per user in 10 minutes; after that you get 429 rate_limited with retryAfter. Many rejected requests freeze 2FA (423 frozen); it opens again when you check who the user is and reset the secret.
What is a case code such as K7P-2QX?
Every login.request answer and every refusal carries a 6-character caseCode. Show it to the user; your team types it into Logs → Look up a case in the dashboard and opens the decision: the reasons, each check and what would have let it through. See Case codes.
Can I protect payments, not only sign-ins?
Yes. Send the action as type (for example SEND_MONEY) and the amount and recipient as details: the phone shows them and the approval is bound to them. Use the approval once. See Consume approval.
Security and privacy
Is push 2FA phishing-resistant?
Not fully. Number matching stops push fatigue, but a fake site working in real time can relay a sign-in. The phishing-resistant method is a passkey, and you can require one for critical actions. See Phishing resistance.
What does Touchque learn about my users?
What you send: externalUsername, the IP address and user agent, the action type and its details. Passwords stay with you; Touchque never sees them.
How do I know a webhook really comes from Touchque?
Every webhook carries an HMAC-SHA256 signature of the body, made with your API secret (the Signing secret under Developers → Webhooks is the same value), in the x-signature header. The SDK's webhook.verify checks the signature and the timestamp; de-duplicate repeats on jti.