Step 2 of 2 · Reference

Callback reference

OT Auth calls your server at four moments in a sign-in. Each call is a POST with a JSON body to your registered base URL plus the path, signed by OT Auth.

Rules for every call

  • Reply within 5 seconds. OT Auth gives up after that and the person sees Couldn't reach the app's server. Please try again. Do slow work after you reply.
  • Reply with JSON. OT Auth reads Status and MessageStatus from the body and ignores the HTTP status code, so a 400 with the right body works as well as a 200. A body that isn't JSON shows the person The app's server sent a reply OT Auth couldn't read.
  • Write field names exactly as shown: Status, not status.
  • Ignore fields you don't use. A call can carry fields not listed here, and new ones may be added. Never refuse a call because of them; the signature covers them like the rest of the body.
  • Check the signature and the API key first. Every call is signed by OT Auth and names the API key whose code was scanned; refuse any call that isn't signed or is for another key, before you act on its body. How to check them.
CallWhenYou answer
/qrvalidateThe person scanned your codeDetails of the waiting browser
/otloginThe person tapped ApproveSigned in, pick an account, or new user
/otregisterA new person agreed to share detailsSigned in
/otrejectThe person tapped Not meAnything; cancel the request

Checking the signature

OT Auth signs every call with its own private key, and you check it with OT Auth's public key. Check the signature before anything else: an unchecked /otlogin would let anyone who can reach your URL sign in as anyone.

FieldTypeWhat it is
X-TimestampUnix secondsWhen OT Auth sent the call.
X-NoncestringRandom, 16 to 64 characters, never used twice.
X-Signaturebase64An ECDSA P-256 signature (DER) over SHA-256 of the six lines below.
APIKeystring, in the bodyThe API key whose QR code was scanned. Covered by the signature, like the rest of the body.

The signed text is six lines joined with \n: OTAUTH-V1, POST, the call's name (/qrvalidate, /otlogin, /otregister or /otreject, whatever path your base URL has), the timestamp, the nonce, and the lowercase hex SHA-256 of the body exactly as received.

Refuse the call when:

  • a header is missing, or the signature doesn't verify with OT Auth's public key;
  • the timestamp is more than 60 seconds from your clock (keep your server's clock synced);
  • you have already accepted that nonce: remember each one for two minutes;
  • its APIKey isn't your own API key. OT Auth signs every app's calls with the same key, so a genuine call can still be about another app's QR code: one registered with your URL, or forwarded to you. Acting on it would sign in whoever opened your page as the person who approved the other app.

Reply 401 with { "Status": false, "MessageStatus": "invalidSignature" }, or "wrongApiKey" for another key, and log it. The person sees Sign-in failed. Please contact the app's support.

ExpressJavaScript
import { createHash, createPublicKey, verify } from "node:crypto";

// OT Auth's public key (base64), from the API Keys page of the OT Auth console.
const OTAUTH_KEY = createPublicKey({
  key: Buffer.from(process.env.OTAUTH_PUBLIC_KEY, "base64"), format: "der", type: "spki",
});

// The signature covers the body's exact bytes: keep them.
app.use(express.json({ verify: (req, res, bytes) => (req.rawBody = bytes) }));

const seen = new Map(); // nonce → when it can be forgotten
otauth.use((req, res, next) => { // the router that holds your four callbacks
  const ts = req.get("X-Timestamp") ?? "";
  const nonce = req.get("X-Nonce") ?? "";
  for (const [n, until] of seen) if (until < Date.now()) seen.delete(n);

  const bodyHash = createHash("sha256").update(req.rawBody ?? "").digest("hex");
  const signed = ["OTAUTH-V1", "POST", req.path, ts, nonce, bodyHash].join("\n");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 60
    && nonce.length >= 16 && nonce.length <= 64 && !seen.has(nonce);
  let valid = false;
  try {
    valid = fresh && verify("sha256", Buffer.from(signed), OTAUTH_KEY,
      Buffer.from(req.get("X-Signature") ?? "", "base64"));
  } catch {}
  if (!valid) return res.status(401).json({ Status: false, MessageStatus: "invalidSignature" });
  seen.set(nonce, Date.now() + 120_000);

  // One OT Auth key signs every app's calls: act only on calls for your own API key.
  if (req.body?.APIKey !== process.env.OTAUTH_API_KEY)
    return res.status(401).json({ Status: false, MessageStatus: "wrongApiKey" });
  next();
});

// Mount it at your callback base path, so req.path is the call's name (/otlogin).
app.use("/api", otauth);

Test your check

Run your check on this call, signed by OT Auth's own signer with a test key. With the 60-second time check turned off (the timestamp is in the past), it must accept the signature; change one character of the body and it must refuse it. Then send your server a real signed call from the Go live dialog on the console's API Keys page: it tells you what your server answered.

Test call
OT Auth public key  MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUhuCHsVlUS6aUfkKSGK9lBinQuDkxu09FjBm7NlZN0k8oprSNJhg/aoUjIrkpBEz/uaMi3SK59ktmjaMW+oo7A==
Path                /qrvalidate
X-Timestamp         1792918969
X-Nonce             EGlutqrB6pm6-tg8bJew-EbP
Body                {"APIKey":"test-api-key","RequestID":"7f3c2a9e-1b4d-4c8e-9f0a-2d6b8e1c5a73"}
X-Signature         MEYCIQD8FovU2K41lTAml+fHTzhH24hHhI4XPumAmxQwHthB+QIhAJ4bFywRNz5R78XtEtJMeF7AaNiy2LZWpVFZJaugPKj4

POST/qrvalidate

Called as soon as someone scans your code, before the app shows the approval screen. Look up the request and describe the browser that's waiting.

RequestHTTP
POST /api/qrvalidate
Content-Type: application/json
X-Timestamp: 1791612255
X-Nonce: q7WvA1x0c2nT4mL9sE3kBw
X-Signature: MEUCIQDf…

{ "APIKey": "YOUR_API_KEY", "RequestID": "1b4e28ba-2fa1-41d2-883f-0016d3cca427" }
Reply: the code is validJSON
{
  "Status": true,
  "MessageStatus": "validateSuccess",
  "Data": {
    "IP": "203.0.113.9",
    "Location": "Mumbai, India",
    "ExpireTime": 1791612345,
    "ExpireDuration": 90
  }
}
FieldTypeWhat it is
IPstringThe waiting browser's IP address, as your server saw it.
LocationstringWhere that browser is, coarse and readable: “Mumbai, India”.
ExpireTimeUnix secondsWhen the code dies. The app counts down to it using the phone's clock. Milliseconds are accepted too. In the past means the person sees “That code has expired”.
ExpireDurationsecondsUsed only when ExpireTime is missing or 0. Without either, the app allows 90 seconds.

If the code is no good, reply Status: false with a MessageStatus from the table under Errors, for example:

Reply: the code expiredJSON
{ "Status": false, "MessageStatus": "expireRequestID" }

POST/otlogin

Called when the person taps Approve sign-in. This is the moment to sign the waiting browser in, or to ask who's new.

RequestHTTP
POST /api/otlogin
Content-Type: application/json
X-Timestamp: 1791612255
X-Nonce: q7WvA1x0c2nT4mL9sE3kBw
X-Signature: MEUCIQDf…

{
  "APIKey": "YOUR_API_KEY",
  "PhoneNo": "+919876543210",
  "RequestType": "login",
  "UserID": 1234567890123456,
  "RequestID": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "AppVersion": "1.1.0 (6)"
}
FieldTypeWhat it is
RequestIDstringYour request. Check it is still pending, and not expired.
UserIDintegerThe person's UID, OT Auth's permanent ID for them. Match it against the UID stored on your users.
PhoneNostringTheir phone number with country code, verified by OT Auth. It can change: people can move their OT Auth account to a new number and keep their UserID. Find the account by UserID, then store the number sent here.
RequestTypestringAlways "login" on this call.
SubUserIDstringPresent only after you offered accounts to pick from (below): the one they chose.
AppVersionstringThe version of the OT Auth app that approved, such as “1.1.0 (6)”. For your records or support; it may be missing.

You know this person: sign them in

Delete the request so it can't be used again, start their session, push it to the waiting page as loginSuccess down the socket stored with the request, then reply:

Reply: signed inJSON
{ "Status": true, "MessageStatus": "loginSuccess" }

The app shows the person Signed in · Acme session is ready on your device.

They have several accounts with you: let them pick

Reply with the account names. The app shows a Sign in as list, remembers their last choice for your app, and calls /otlogin again with the chosen SubUserID. On that second call, check it is one of the accounts you listed for this UserID, then sign in to it and reply loginSuccess. Each name is shown as you wrote it and comes back as the SubUserID, so make the names unique among one person's accounts. The app lists up to 10 names, each up to 40 characters, and leaves out longer ones.

Reply: pick an accountJSON
{
  "Status": true,
  "Data": { "SubUserID": ["Personal", "Acme Traders"] }
}

They had an account before you added OT Auth: link it once

If no account has this UserID, look for one with this PhoneNo that has no OT Auth UserID yet. It is the person's account from before OT Auth, and OT Auth has just verified the number: save the UserID on it and sign them in. From then on you find them by UserID, whatever their number becomes.

ExpressJavaScript
let user = await users.findByOtAuthUserId(UserID);
if (!user) {
  // From before OT Auth: this verified number, and no UserID yet. Link it once.
  const earlier = await users.findByPhone(PhoneNo);
  if (earlier && !earlier.otauthUserId) user = await users.setOtAuthUserId(earlier.id, UserID);
}
// Still none: a new person. Ask for details (below).

Link only an account that has no UserID: one with another UserID belongs to someone else, and the number stored on it may be out of date. A number you stored long ago may also have been given to someone new since. If your numbers are old or were never verified, ask for something only the owner knows, such as their password, before you link.

You don't know them yet: ask for details

Leave the request pending and reply with the profile fields you want. The app lists them with your PrivacyMessage, and the person ticks what to share. Then OT Auth calls /otregister with the same RequestID.

Reply: new personJSON
{
  "Status": false,
  "MessageStatus": "userNotFound",
  "RegistrationAllowed": true,
  "PrivacyMessage": "Acme uses your name and email for your account and receipts.",
  "FormField": [
    { "FieldName": "PhoneNo", "Required": true },
    { "FieldName": "FirstName", "Required": true },
    { "FieldName": "LastName", "Required": false },
    { "FieldName": "Email", "Required": false }
  ]
}

Field names are matched without regard to case. These are the ones OT Auth can share:

FirstName MiddleName LastName Email PhoneNo Address Address2 PostalCode City State Country

  • An unknown field that is not required is dropped quietly.
  • An unknown field marked Required fails the sign-in with Sign-in failed. OT Auth also calls /otregister with MissingFields, an array of the field names it lacks, so you can spot the mistake; reply Status: false.
  • To refuse new sign-ups, reply "RegistrationAllowed": false. The person sees Registration Not Allowed.

POST/otregister

Called after a new person agrees to share the details you asked for. Create their account, sign the browser in, and reply as for /otlogin.

RequestHTTP
POST /api/otregister
Content-Type: application/json
X-Timestamp: 1791612255
X-Nonce: q7WvA1x0c2nT4mL9sE3kBw
X-Signature: MEUCIQDf…

{
  "APIKey": "YOUR_API_KEY",
  "UserID": 1234567890123456,
  "RequestID": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "FormField": { "PhoneNo": "+919876543210", "FirstName": "Asha", "Email": "asha@example.com" },
  "AppVersion": "1.1.0 (6)"
}
FieldTypeWhat it is
RequestIDstringThe same pending request as the /otlogin before it.
UserIDintegerThe person's UID. Save it on the new account.
FormFieldobjectOnly the fields the person ticked, keyed by the names you asked for, with values from their OT Auth profile. A value can be an empty string when their profile has none. Fill in the new account with them; never use them to find or merge an existing one.
AppVersionstringAs in /otlogin: the version of the OT Auth app that approved. It may be missing.

Handle it in this order:

  1. Check the request is still waiting. If not, answer invalidRequestID or expireRequestID, and create nothing: never make an account for an unknown or expired code.
  2. Look for an existing account by UserID and by phone number. If either exists, answer alreadyRegistered.
  3. Create the account with the person's UID, and delete the request so it can't be used again.
  4. Push the session to the waiting page as loginSuccess, then reply exactly as for /otlogin.

POST/otreject

Called when the person taps Not me — report this. They did not start this sign-in.

RequestHTTP
POST /api/otreject
Content-Type: application/json
X-Timestamp: 1791612255
X-Nonce: q7WvA1x0c2nT4mL9sE3kBw
X-Signature: MEUCIQDf…

{ "APIKey": "YOUR_API_KEY", "RequestID": "1b4e28ba-2fa1-41d2-883f-0016d3cca427" }

Delete the request so it can never be approved, and push requestRejected to the waiting page so it can say Sign-in was declined on the phone and offer a new code. OT Auth doesn't read your reply; it only logs a status that isn't 2xx. The person is told That code was revoked. Nobody was signed in. whatever you answer. A code that's already gone can get invalidRequestID. Consider alerting the account owner if rejects keep coming for one account.

Errors

Reply Status: false with one of these MessageStatus values on /qrvalidate, /otlogin or /otregister:

MessageStatusUse it whenThe person sees
expireRequestIDThe request has passed its expiryThis QR code has expired. Scan a new one
invalidRequestIDUnknown, already used or rejected requestThis QR code is no longer valid. Scan the newest one
userNotFoundA new person (see above)The share-details screen
alreadyRegistered/otregister for someone who already has an accountYou are Already Registered
requiredEmailYou can't continue without an emailEmail is Required
anything elseAny other failureSign-in failed. Please contact the app's support

And when your server itself is the problem:

What happenedThe person sees
No reply within 5 seconds, or your server is unreachableCouldn't reach the app's server. Please try again
The reply isn't JSONThe app's server sent a reply OT Auth couldn't read
Your API key is switched offThis app's OT Auth sign-in is switched off
Your callback URL is a private or local address, or its name resolves to oneThis app's callback URL is not a valid public address