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

  1. 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.
  2. 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.
  3. 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.
  4. OT Auth tells you who approvedIt calls /otlogin with 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.
  5. 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 /otreject instead, and you cancel the request.

The same flow, call by call:

Browser
Your server
OT Auth server
OT Auth app
  1. 01 WebSocket · qrLoginRequest
  2. 02 SessionRequested · QR link + expiry
  3. 03 Person scans the code
  4. 04 Scanned code, signed by the phone
  5. 05 POST /qrvalidate
  6. 06 IP, location, expiry
  7. 07 Registered app name + your details
  8. Person taps Approve
  9. 09 Approval, signed by the phone
  10. 10 POST /otlogin · UserID, PhoneNo
  11. 11 loginSuccess, same socket
  12. 12 loginSuccess
  13. 13 Signed in
A first-time visitor sees one extra step between 10 and 11: OT Auth asks them which details to share, then calls /otregister instead of finishing /otlogin.

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 localhost or 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.

  1. Sign inOpen the console and scan its code with OT Auth.
  2. Add your organisationOn the Dashboard, choose Add New Firm and enter your organisation's details.
  3. Generate an API keyOn API Keys, choose Generate API Key, accept the developer terms and fill in:
    FieldWhat to enter
    Application NameYour app's name as people know it. The phone asks Sign in to Acme? using this name, never a name your website sends.
    URLYour callback base URL. OT Auth adds the path: enter https://acme.example/api and it calls https://acme.example/api/otlogin. It must be a public https address.
  4. Copy your keysThe dialog shows them together:
    KeyWhere it goes
    API KeyYour server's settings. It goes into every QR code you show.
    OT Auth Public KeyYour 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 KeyShown 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.
  5. 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

  1. 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 →
  2. Answer OT Auth's four calls/qrvalidate, /otlogin, /otregister and /otreject, under your callback base URL. Callback reference →
  3. Check that each call comes from OT Auth, for your keyVerify the signature with OT Auth's public key, and that the call's APIKey is your own, before you act on the body. Checking the signature →
  4. Send the result to the waiting pageSigned in, declined or expired, down the socket that asked for the code. Listen for the outcome →
  5. 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

TermMeaning
RequestIDYour ID for one sign-in attempt. You create it, print it in the QR code, and OT Auth sends it back on every call.
UserIDOT Auth's permanent ID for the person who approved. Store it on your user record; it is how you recognise them next time.
PhoneNoThe person's phone number in international format, verified by OT Auth.
SubUserIDOptional. If one person has several accounts with you, you list them and the person picks one.
FormFieldProfile details you ask a new person to share: their name, email, address and so on.
Callback base URLThe 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”.