Before and after you deploy

Go live

What your server needs to know, how to put it behind a proxy without breaking the sign-in, the checks to run once it's up, and what each failure looks like on the person's phone.

Settings

Name them however you like; your server needs all five.

SettingWhere it comes fromExample's name
API keyFrom the OT Auth console. It's printed in every QR code, so it isn't a secret.OTAUTH_API_KEY
OT Auth's public keyFrom the console's API Keys page. Checks the signature on every callback. Not a secret.OTAUTH_PUBLIC_KEY
Code lifetime90 seconds, which matches what the app tells people.QR_TTL
Session signing keysYours: long and random, kept in the environment. Refuse to start without them.your own
Callback base URLThe URL on your API key in the console, e.g. https://acme.example/api. OT Auth adds /qrvalidate and the rest. It must be a public address: OT Auth won't call private or local ones.—

Behind nginx

One location block carries your API, the sign-in WebSocket and OT Auth's callbacks. Three details decide whether it works:

nginx
map $http_upgrade $connection_upgrade {
  default upgrade;
  ""      close;
}

server {
  # listen 443 ssl; server_name acme.example; your certificates…

  location /api/ {
    proxy_pass http://127.0.0.1:3000;                # no trailing slash: keep /api
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;          # the sign-in WebSocket
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;   # overwrite, never append
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
  • No trailing slash on proxy_pass. With one, nginx strips /api, and every route, the WebSocket and the callbacks answer 404.
  • The Upgrade and Connection headers. Without them the sign-in page never gets a code: the WebSocket can't open.
  • X-Forwarded-For $remote_addr. It replaces whatever the caller sent. Your app then sees the real address, which is what the person checks on their phone.
ExpressJavaScript
// If you read req.ip: believe X-Forwarded-For only from the proxy on this machine.
app.set("trust proxy", "loopback");

After deploying, check

  1. The page shows a codeA QR code with a 90-second countdown, and an Open OT Auth App button on phones.
  2. Your key is live, and your server answers a test callOn the console's API Keys page the key shows Live (verify your domain in its Go live dialog). In the same dialog, Send test call must say Signature accepted.
  3. The approval screen is honestScan it: the phone shows your registered app name and your own public IP address and city.
  4. A new person can joinWith an account you haven't used before, the app asks which details to share; after sharing, the page signs in.
  5. A known person goes straight inScan again and approve: the page signs in with no questions.
  6. Not me worksScan and tap Not me: the page says the sign-in was declined, and that code no longer works.
  7. Codes dieLeave a code for 90 seconds: scanning it fails, and the page offers a fresh one.
  8. Strangers are turned awaySend POST /api/otlogin from your own laptop: it gets a 401 invalidSignature, and your log records the refusal.
  9. The clock is rightYour server keeps time by NTP. A clock more than 60 seconds off refuses OT Auth's genuine calls.

Troubleshooting

The person sees OT Auth's message; your log and this table say why.

The phone showsUsually meansFix
Sign-in failed. Please contact the app's supportOn every scan, with invalidSignature in your log: the public key you set isn't OT Auth's, your clock is more than 60 seconds off, or your JSON parser changed the body before the check. With wrongApiKey: the key you compare with isn't the one your QR codes carry. Otherwise you answered a MessageStatus OT Auth doesn't know.Copy the OT Auth Public Key from the console again, sync the clock, check the raw body; compare APIKey with the key in your QR codes; or use a MessageStatus from the callback reference.
Couldn't reach the app's server. Please try againOT Auth couldn't reach your callback URL, or you took over 5 seconds.Check the registered URL and your firewall; reply first, do slow work after.
The app's server sent a reply OT Auth couldn't readYour reply wasn't JSON, often a proxy error page.Check the proxy passes /api/… with the prefix intact.
Request ID is requiredYou answered requiredRequestID for a code you don't know.Answer invalidRequestID for unknown or used codes.
This QR code is no longer valid. Scan the newest oneYour server doesn't know the code: it was used, replaced by a newer one, its page closed, or another instance holds it.Scan the newest code. With several instances, see Full example → Storage.
This QR code has expired. Scan a new oneThe code ran out, or the phone's clock is far off.Scan the fresh code; check the phone's automatic time.
This code isn't for OT AuthThe link isn't https://auth.orvixtech.com/qr-login, or the token lacks apikey or requestId.The link inside the code
This app is still being tested. Only its own team can sign in until it's approvedYour key is in test mode or in review, and the person isn't a member of your organisation in the console.Verify your domain in the key's Go live dialog. If it says In review, contact us.
This app's OT Auth sign-in is switched offYour key is switched off.Switch it on in the console's API Keys page, or contact us if you didn't switch it off.
This app's callback URL is not a valid public addressYour callback URL is a private or local address, or its name resolves to one.Set a public https URL on your key; while developing, use an HTTPS tunnel's address.
This QR code isn't from an app registered with OT AuthThe key in the code doesn't match any API key in the console.Check the key your server puts in the token.
127.0.0.1 or your proxy's address as the IPYour proxy doesn't forward the caller's address, or your app doesn't trust it.Behind nginx
The sign-in page never shows a codeThe WebSocket can't open, or your server closed it: the proxy drops Upgrade, or the page's Origin isn't the one your server accepts (another host, or a proxy that changes Host).Check the proxy headers above, and compare with your sign-in page's real origin.
Approved, but the page never signs inThe page's socket closed, or the outcome went to a server instance that doesn't hold it.Keep the page open while approving; with several instances, see Full example → Storage.

Still stuck? Contact us and choose “Integrate OT Auth”.