Skip to main content
View as Markdown

Verify users with OTP

Use a one-time password when you need to confirm that a user controls an international phone number. Inttegro sends the token by SMS and records each verification attempt; your application must inspect the attempt verdict before granting access.

Note

The MCP tool catalog does not currently expose OTP initiation or verification. Keep OTP submission and verdict checks in your trusted backend; use MCP for adjacent customer or order investigation only when that context is relevant.

Prerequisites

  • The user's phone number in international format
  • A server-side place to associate the typed OTP transaction ID with the pending action

Initiate the SMS verification

Call Initiate OTP transaction with recipient, serviceName, and tokenSize. Set purpose to sign_in so the message explains why the code was sent. The current API requires a token size from 5 through 10. The service name must be 2-20 characters; an optional sender must be 3-12 characters. Validity defaults to 10 minutes and can be set from 3 through 10,080 minutes.

Persist the returned ID in the form ot_<TRANSACTION_ID>. A transaction can be Inttegro.OtpStatuses.PendingDelivery before transmission details are available and Inttegro.OtpStatuses.PendingVerification after the SMS is sent.

Verify the submitted token

Submit the transaction ID, the same international phone number, and the token entered by the user. An HTTP 200 response means the attempt was recorded, not that the token matched. Continue only when verificationAttempt.result.verdict is "pass".

SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})

const recipient = '<USER_PHONE_E164>'
const otpCodeFromUser = '<OTP_ENTERED_BY_USER>'

const initiated = await inttegro.otp.initiate({
  requestMeta: { idempotencyKey: "verify-user-123" },
  recipient,
  purpose: Inttegro.OtpPurposes.SignIn,
  sender: "MyApp",
  serviceName: "MyApp",
  tokenAlphabetType: "numeric",
  tokenSize: 6,
})

if (!initiated.id) {
  throw new Error('The OTP transaction did not include an ID')
}

const verified = await inttegro.otp.verify({
  recipient,
  token: otpCodeFromUser,
  transactionId: initiated.id,
})

if (verified.verificationAttempt?.result?.verdict !== 'pass') {
  throw new Error('The supplied OTP did not match')
}

Do not log the submitted token or verification response body. If the verdict is "fail", keep the protected action pending and let the user retry only within your attempt policy. Use Lookup OTP transaction to refresh the transaction state, or Cancel OTP transaction when the flow is abandoned.