Integration guide
Add OT Auth sign‑in to your app
People sign in to your website by scanning a QR code and approving on their phone: no password to type, nothing to remember. Your server shows the code and answers four HTTPS calls from OT Auth. There is no SDK to install, just JSON over HTTPS, so it works with any language or framework.
How a sign-in works
- Your sign-in page shows a codeThe page asks your server for a sign-in code. Your server creates a one-time sign-in request, remembers which page asked for it, and sends back a QR code.
- The person scans it with OT AuthOT Auth asks your server about that request (
/qrvalidate). You answer with the IP address and city of the browser that is waiting, and when the code expires. - They check the details and approveThe phone shows your app's name, where the sign-in is coming from, and a countdown. If it's them, they tap Approve. If it isn't, they tap Not me.
- OT Auth tells you who approvedIt calls
/otloginwith the person's OT Auth user ID and verified phone number. If you don't know them yet, you ask for profile details, and OT Auth sends the ones they agree to share to/otregister. - Your server signs the page inYou start a session for that person and push it to the page that is waiting. The page is signed in. After Not me, OT Auth calls
/otrejectinstead, and you cancel the request.
The same flow, call by call:
- 01 WebSocket · qrLoginRequest
- 02 SessionRequested · QR link + expiry
- 03 Person scans the code
- 04 Scanned code, signed by the phone
- 05 POST /qrvalidate
- 06 IP, location, expiry
- 07 Registered app name + your details
- Person taps Approve
- 09 Approval, signed by the phone
- 10 POST /otlogin · UserID, PhoneNo
- 11 loginSuccess, same socket
- 12 loginSuccess
- 13 Signed in
Your server never talks to the phone, and the phone never talks to your server: OT Auth sits between them. Every call OT Auth makes to you is signed and names the API key whose code was scanned, so your server can prove it came from OT Auth, about its own code, before it signs anyone in.
Before you start
- OT Auth on your phone. You use it to sign in to the OT Auth console and to test your sign-in page.
- A server reachable over public HTTPS. OT Auth only calls public addresses, never
localhostor a private network. While you develop, expose your machine through an HTTPS tunnel and use the tunnel's address. - A WebSocket between your sign-in page and your server, so your server can tell the page the moment someone approves. The examples use Node.js with Express and
ws; any stack works. - A clock kept in sync (NTP). Your server refuses signed calls more than 60 seconds old, so a clock that drifts refuses real ones.
Get your keys
Your app gets its keys from the OT Auth console, firm.orvixtech.com. It needs a computer browser.
- Sign inOpen the console and scan its code with OT Auth.
- Add your organisationOn the Dashboard, choose Add New Firm and enter your organisation's details.
- Generate an API keyOn API Keys, choose Generate API Key, accept the developer terms and fill in:
Field What to enter Application Name Your app's name as people know it. The phone asks Sign in to Acme? using this name, never a name your website sends. URL Your callback base URL. OT Auth adds the path: enter https://acme.example/apiand it callshttps://acme.example/api/otlogin. It must be a public https address. - Copy your keysThe dialog shows them together:
Key Where it goes API Key Your server's settings. It goes into every QR code you show. OT Auth Public Key Your server's settings. It checks that each call really comes from OT Auth (Checking the signature). It also stays on the API Keys page. Private Key Shown only once. Only code sign-in uses it, to sign your server's calls to OT Auth. Keep it on your server with your other secrets, even if you don't use it yet. - Verify your domainA new key starts in test mode: only members of your organisation in the console can sign in with it. Open the key's Go live dialog, add the TXT record it shows to your domain's DNS and choose Verify domain. Most keys then go live by themselves. A name that looks like a well-known brand, or doesn't match your domain, is reviewed by us first. Moving your callback URL to another domain puts the key back in test mode.
Make a second API key for your staging server, with its own URL, so you can test without touching production. On the same page you can change a key's URL, switch it off, or replace it.
Build it, step by step
- Show the sign-in codeYour page opens a WebSocket and asks for a code. Your server creates the request, keeps the page's socket with it, and sends back the QR link. Show the sign-in code →
- Answer OT Auth's four calls
/qrvalidate,/otlogin,/otregisterand/otreject, under your callback base URL. Callback reference → - Check that each call comes from OT Auth, for your keyVerify the signature with OT Auth's public key, and that the call's
APIKeyis your own, before you act on the body. Checking the signature → - Send the result to the waiting pageSigned in, declined or expired, down the socket that asked for the code. Listen for the outcome →
- Review, deploy and testGo through the security checklist, put your server behind your proxy, and run the checks in Go live.
Words used in this guide
| Term | Meaning |
|---|---|
RequestID | Your ID for one sign-in attempt. You create it, print it in the QR code, and OT Auth sends it back on every call. |
UserID | OT Auth's permanent ID for the person who approved. Store it on your user record; it is how you recognise them next time. |
PhoneNo | The person's phone number in international format, verified by OT Auth. |
SubUserID | Optional. If one person has several accounts with you, you list them and the person picks one. |
FormField | Profile details you ask a new person to share: their name, email, address and so on. |
| Callback base URL | The URL on your API key. OT Auth adds /qrvalidate, /otlogin, /otregister or /otreject to it. |
Start here
Questions while you build? Contact us and choose “Integrate OT Auth”.