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.
| Setting | Where it comes from | Example's name |
|---|---|---|
| API key | From the OT Auth console. It's printed in every QR code, so it isn't a secret. | OTAUTH_API_KEY |
| OT Auth's public key | From the console's API Keys page. Checks the signature on every callback. Not a secret. | OTAUTH_PUBLIC_KEY |
| Code lifetime | 90 seconds, which matches what the app tells people. | QR_TTL |
| Session signing keys | Yours: long and random, kept in the environment. Refuse to start without them. | your own |
| Callback base URL | The 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:
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
UpgradeandConnectionheaders. 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.
// If you read req.ip: believe X-Forwarded-For only from the proxy on this machine.
app.set("trust proxy", "loopback");After deploying, check
- The page shows a codeA QR code with a 90-second countdown, and an Open OT Auth App button on phones.
- 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.
- The approval screen is honestScan it: the phone shows your registered app name and your own public IP address and city.
- 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.
- A known person goes straight inScan again and approve: the page signs in with no questions.
- Not me worksScan and tap Not me: the page says the sign-in was declined, and that code no longer works.
- Codes dieLeave a code for 90 seconds: scanning it fails, and the page offers a fresh one.
- Strangers are turned awaySend
POST /api/otloginfrom your own laptop: it gets a 401invalidSignature, and your log records the refusal. - 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 shows | Usually means | Fix |
|---|---|---|
| Sign-in failed. Please contact the app's support | On 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 again | OT 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 read | Your reply wasn't JSON, often a proxy error page. | Check the proxy passes /api/… with the prefix intact. |
| Request ID is required | You 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 one | Your 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 one | The 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 Auth | The 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 approved | Your 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 off | Your 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 address | Your 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 Auth | The 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 IP | Your proxy doesn't forward the caller's address, or your app doesn't trust it. | Behind nginx |
| The sign-in page never shows a code | The 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 in | The 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”.