Skip to main content

One-time passwords

One-time passwords let you check that a customer controls a phone number before you continue a sensitive flow. Inttegro generates a short-lived SMS code, sends it to the recipient, and records the verification attempt.

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 only for adjacent customer or order investigation when that context is relevant.

Use this page to understand the OTP boundary. Use the OTP API reference for exact request attributes and response shapes.

What OTPs are for

Use OTPs for explicit phone-control checks:

  • customer sign-in or sign-up;
  • phone-number confirmation;
  • sensitive account changes;
  • high-risk action approval; and
  • recovery flows where SMS verification is appropriate.

Do not use Chimes as an OTP substitute. Chimes are notifications; OTPs have a verification endpoint and a verdict-bearing response.

Verification model

An OTP transaction represents one generated code and its delivery/verification lifecycle.

StepWhat happens
InitiateYour backend requests a code for a recipient and service name.
DeliverInttegro sends the code by SMS, synchronously or asynchronously depending on request options.
CollectYour application asks the customer to enter the code.
VerifyYour backend submits the transaction ID, recipient, and customer-entered token.
DecideYour application continues only when the verification verdict is pass.

An HTTP 200 from verification means the attempt was recorded. It does not by itself mean the submitted token was correct. Authorize only from verification_attempt.result.verdict: "pass".

Initiation rules

The fields most integrations need are:

  • recipient - international phone number;
  • service_name - customer-facing service label;
  • token_size - code length from 5 through 10;
  • token_alphabet_type - optional alphabet, such as numeric or alphanumeric;
  • validity_duration_in_minutes - optional expiry window; and
  • async_delivery - optional delivery mode when your integration can handle delayed transmission details.

Keep the service name recognizable. Customers should understand which product requested the code.

Security and UX rules

Build the surrounding flow deliberately.

  • Store the OTP transaction ID server-side with the pending action.
  • Never log submitted tokens.
  • Never expose generated tokens in your own application.
  • Rate-limit initiation and verification attempts.
  • Show clear expiry and resend behavior.
  • Treat delivery status as delivery telemetry, not as proof of verification.

Implement verification

Use Initiate OTP transaction to start the flow and Verify OTP to submit the customer-entered code.

Use Lookup OTP transaction when you need state refresh. If the protected flow is abandoned, stop accepting that OTP transaction in your own application state.

The maintained walkthrough is Verify users with OTP. It shows the verdict check your application must perform.