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
StatusandMessageStatusfrom 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, notstatus. - 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.
| Call | When | You answer |
|---|---|---|
/qrvalidate | The person scanned your code | Details of the waiting browser |
/otlogin | The person tapped Approve | Signed in, pick an account, or new user |
/otregister | A new person agreed to share details | Signed in |
/otreject | The person tapped Not me | Anything; 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.
| Field | Type | What it is |
|---|---|---|
X-Timestamp | Unix seconds | When OT Auth sent the call. |
X-Nonce | string | Random, 16 to 64 characters, never used twice. |
X-Signature | base64 | An ECDSA P-256 signature (DER) over SHA-256 of the six lines below. |
APIKey | string, in the body | The 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
APIKeyisn'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.
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.
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+QIhAJ4bFywRNz5R78XtEtJMeF7AaNiy2LZWpVFZJaugPKj4POST/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.
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" }{
"Status": true,
"MessageStatus": "validateSuccess",
"Data": {
"IP": "203.0.113.9",
"Location": "Mumbai, India",
"ExpireTime": 1791612345,
"ExpireDuration": 90
}
}| Field | Type | What it is |
|---|---|---|
IP | string | The waiting browser's IP address, as your server saw it. |
Location | string | Where that browser is, coarse and readable: “Mumbai, India”. |
ExpireTime | Unix seconds | When 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”. |
ExpireDuration | seconds | Used 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:
{ "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.
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)"
}| Field | Type | What it is |
|---|---|---|
RequestID | string | Your request. Check it is still pending, and not expired. |
UserID | integer | The person's UID, OT Auth's permanent ID for them. Match it against the UID stored on your users. |
PhoneNo | string | Their 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. |
RequestType | string | Always "login" on this call. |
SubUserID | string | Present only after you offered accounts to pick from (below): the one they chose. |
AppVersion | string | The 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:
{ "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.
{
"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.
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.
{
"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
Requiredfails the sign-in with Sign-in failed. OT Auth also calls/otregisterwithMissingFields, an array of the field names it lacks, so you can spot the mistake; replyStatus: 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.
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)"
}| Field | Type | What it is |
|---|---|---|
RequestID | string | The same pending request as the /otlogin before it. |
UserID | integer | The person's UID. Save it on the new account. |
FormField | object | Only 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. |
AppVersion | string | As in /otlogin: the version of the OT Auth app that approved. It may be missing. |
Handle it in this order:
- Check the request is still waiting. If not, answer
invalidRequestIDorexpireRequestID, and create nothing: never make an account for an unknown or expired code. - Look for an existing account by
UserIDand by phone number. If either exists, answeralreadyRegistered. - Create the account with the person's UID, and delete the request so it can't be used again.
- 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.
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:
| MessageStatus | Use it when | The person sees |
|---|---|---|
expireRequestID | The request has passed its expiry | This QR code has expired. Scan a new one |
invalidRequestID | Unknown, already used or rejected request | This QR code is no longer valid. Scan the newest one |
userNotFound | A new person (see above) | The share-details screen |
alreadyRegistered | /otregister for someone who already has an account | You are Already Registered |
requiredEmail | You can't continue without an email | Email is Required |
| anything else | Any other failure | Sign-in failed. Please contact the app's support |
And when your server itself is the problem:
| What happened | The person sees |
|---|---|
| No reply within 5 seconds, or your server is unreachable | Couldn't reach the app's server. Please try again |
| The reply isn't JSON | The app's server sent a reply OT Auth couldn't read |
| Your API key is switched off | This app's OT Auth sign-in is switched off |
| Your callback URL is a private or local address, or its name resolves to one | This app's callback URL is not a valid public address |