--- title: "One-time passwords" description: "Generate and verify one-time passwords for secure authentication and verification flows." canonical: "https://studio.inttegro.com/api/otps" format: inttegro-machine-docs/v1 language: "TypeScript" sdk_version: "v12.0.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/typescript/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 493 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 4780 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Generate and verify one-time passwords for secure authentication and verification flows. This TypeScript representation uses the selected SDK's native names wherever Studio has a verified mapping. ### Five questions #### Q1. Is One-time passwords the right source for this task? Use this reference for generate and verify one-time passwords for secure authentication and verification flows. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order. #### Q2. Does a successful verify request prove the code matched? **HTTP success is not proof that the code matched.** Verify returns a recorded attempt for both matching and non-matching tokens. Continue the protected action only when [`verificationAttempt.result.verdict`](https://typescript.inttegro.dev/v12.0.0) is [`Inttegro.OtpVerificationVerdicts.Pass`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpVerificationVerdicts.html#pass). #### Q3. How is verification bound to the initiated transaction? **Bind verification to the initiated transaction.** Submit the returned transaction ID, the same normalized recipient, and the customer-entered token. Do not substitute a new recipient or infer success from delivery status. #### Q4. How should token material be handled? **Treat token material as sensitive.** Initiation and lookup never return the generated code. Do not log the submitted or presented token, include it in analytics, or place it in model context. #### Q5. What is the difference between delivery and verification? **Distinguish delivery from verification.** Pending delivery means transmission details may not exist yet; pending verification means the SMS gateway or email provider accepted the message and the transaction awaits an attempt. Use [Chimes](https://studio.inttegro.com/machine/typescript/api/chimes.md) for ordinary messaging, not OTP delivery semantics. ## Document content # One-time passwords (OTPs) Use One-Time Passwords (OTPs) to confirm that a customer controls a phone number or email address before you sign them in, change sensitive account data, or approve an action. Inttegro generates and sends the time-limited code; your application should continue only after verification returns a [`Inttegro.OtpVerificationVerdicts.Pass`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpVerificationVerdicts.html#pass) verdict. ## Authorize only from the verification verdict The four decision rules are in the machine preamble above. ## The OTP transaction object An OTP transaction represents one code from generation through delivery and verification. Initiation and lookup responses never expose the generated code: collect the code from the customer, then submit that value to the verify endpoint. ### Properties - [`cancelReason`](https://typescript.inttegro.dev/v12.0.0) — `string` Explanation for why this transaction was canceled. Omitted unless [`transaction.status`](https://typescript.inttegro.dev/v12.0.0) is [`Inttegro.OtpStatuses.Canceled`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#canceled). - [`canceledAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` When this transaction was canceled. Omitted unless [`transaction.status`](https://typescript.inttegro.dev/v12.0.0) is [`Inttegro.OtpStatuses.Canceled`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#canceled). - [`expiresAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` When this token expires and can no longer be verified. - [`fullMessage`](https://typescript.inttegro.dev/v12.0.0) — `string` The message template with the service name substituted and the token placeholder preserved as `'{token}'`. The token value is not included in this field. - [`id`](https://typescript.inttegro.dev/v12.0.0) — `string` Unique identifier for this transaction—use it to verify tokens and lookup transaction status. - [`initiatedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` When this transaction was created and token generation began. - [`status`](https://typescript.inttegro.dev/v12.0.0) — `string` Current transaction status. Possible values are [`Inttegro.OtpStatuses.Canceled`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#canceled), [`Inttegro.OtpStatuses.Expired`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#expired), [`Inttegro.OtpStatuses.Pending`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#pending), [`Inttegro.OtpStatuses.PendingDelivery`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#pendingdelivery), [`Inttegro.OtpStatuses.PendingVerification`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#pendingverification), and [`Inttegro.OtpStatuses.Verified`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#verified). [`Inttegro.OtpStatuses.PendingDelivery`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#pendingdelivery) means delivery-attempt fields are not available yet; [`Inttegro.OtpStatuses.PendingVerification`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#pendingverification) means the message was sent and the transaction is waiting for a verification attempt. - [`transmission`](https://typescript.inttegro.dev/v12.0.0) Delivery details for the OTP message. Recipient and sender are always present; attempt fields are omitted until delivery begins. - [`transmission.recipient`](https://typescript.inttegro.dev/v12.0.0) — `string` Normalized international phone number or bare email address targeted by delivery. - [`transmission.senderId`](https://typescript.inttegro.dev/v12.0.0) — `string` SMS sender identifier or noreply@inttegro.com for email OTP. - [`transmission.sentAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` When the message was sent. Omitted until the delivery attempt. - [`transmission.sentVia`](https://typescript.inttegro.dev/v12.0.0) — `string` Delivery mechanism: `"sms"` or `"email"`. Omitted until the delivery attempt starts. - [`transmission.status`](https://typescript.inttegro.dev/v12.0.0) — `string` Delivery status: [`Inttegro.OtpTransmissionStatuses.Submitted`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpTransmissionStatuses.html#submitted), [`Inttegro.OtpTransmissionStatuses.Delivered`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpTransmissionStatuses.html#delivered), or [`Inttegro.OtpTransmissionStatuses.Failed`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpTransmissionStatuses.html#failed) for SMS. accepted means an email provider accepted the send, not that the inbox received it. Omitted until the delivery attempt. ## Initiate OTP transaction Generate a one-time password, deliver it by SMS to an international phone number or by email to a bare email address, and return a typed transaction ID for verification. ### Required attributes - `recipient` — `string` International phone number that will receive SMS, such as `+233241234567`, or a bare email address. The transport is inferred unless specified. - `serviceName` — `string` Service or application name substituted for `'{service}'` in the message template. Length: 2-20 characters. - `purpose` — `string` — required Intent of the verification flow. Supported values are `account_creation`, `account_recovery`, `email_verification`, `financial_account_verification`, `password_reset`, `payment_confirmation`, `payment_method_verification`, `payout_confirmation`, `phone_verification`, `sensitive_action`, `sign_in`, `transaction_confirmation`, and `unspecified`. Unsupported values are rejected. Use `unspecified` explicitly for a general verification request. - `tokenSize` — `number` Generated token length. The current API requires a value from 5 through 10, inclusive. ### Optional attributes - `asyncDelivery` — `boolean` When `false` or omitted, the request waits for the initial transmission attempt. When `true`, the transaction can be returned before transmission details are available, with status [`Inttegro.OtpStatuses.PendingDelivery`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpStatuses.html#pendingdelivery). - `messageTemplate` — `string` Custom SMS body or email copy. It must include `'{token}'` exactly once and can include `'{service}'`. Email sends it as the plain-text fallback and renders the copy around the code in a branded HTML layout. For email, custom copy overrides the purpose-specific default body, but the selected purpose still controls the subject and heading. If omitted, the API uses its transport-specific purpose-aware template. - `sender` — `string` SMS sender identifier (3-12 characters). Email OTP always uses `'{service_name} '`; omit this field for email. - `preferred_gateway` — `string` — wire-only Optional SMS gateway. Do not supply it for email OTP; email uses the configured default provider. - `transport` — `enum` — wire-only Optional `"sms"` or `"email"`. A phone recipient selects SMS and an email recipient selects email when omitted. - `tokenAlphabet` — `string` Custom alphabet for token generation. Pass a string of characters to use (for example, `"0123456789ABCDEF"` for hexadecimal tokens). Mutually exclusive with `tokenAlphabetType`—use one or the other, not both. - `tokenAlphabetType` — `AlphabetType` Predefined alphabet type for token generation. Supported values are [`Inttegro.OtpAlphabetTypes.Alpha`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpAlphabetTypes.html#alpha), [`Inttegro.OtpAlphabetTypes.Alphanumeric`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpAlphabetTypes.html#alphanumeric), and [`Inttegro.OtpAlphabetTypes.Numeric`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpAlphabetTypes.html#numeric). If neither alphabet field is supplied, the default alphabet is alphanumeric. Mutually exclusive with `tokenAlphabet`. - `validityDurationInMinutes` — `number` How long the token remains valid. Accepted values are 3 through 10,080 minutes (7 days), inclusive. Defaults to 10 minutes. The fully rendered SMS, including the generated code and substituted service name, must be no longer than 120 characters; email text is limited to 2,048 characters. The transaction expires after its validity window even if delivery is delayed. For email OTP, send a bare email recipient and omit the SMS-only `preferred_gateway` field. The `'{service_name} '` From mailbox and SES provider are selected automatically: ```json { "recipient": "customer@example.com", "service_name": "Inttegro", "token_size": 6, "purpose": "sign_in" } ``` The verification request uses the returned transaction ID, this same recipient, and the code supplied by the customer. ### Response With synchronous delivery, inspect [`transaction.transmission.status`](https://typescript.inttegro.dev/v12.0.0): [`Inttegro.OtpTransmissionStatuses.Submitted`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpTransmissionStatuses.html#submitted) means the SMS message was submitted for delivery, [`Inttegro.OtpTransmissionStatuses.Delivered`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpTransmissionStatuses.html#delivered) means delivery was confirmed, and [`Inttegro.OtpTransmissionStatuses.Failed`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpTransmissionStatuses.html#failed) means the delivery attempt failed. For email, `accepted` means SES accepted the send; it does not prove inbox delivery. **Request — POST /otp/initiate** ```typescript import * as Inttegro from '@inttegro/inttegro-sdk' const inttegro = new Inttegro.InttegroClient({ apiKey: process.env.INTTEGRO_API_KEY!, }) const result = await inttegro.otp.initiate({ messageTemplate: "Your {service} code is {token}.", purpose: "transaction_confirmation", recipient: "+233241234567", sender: "Acme", serviceName: "Acme Bank", tokenAlphabetType: "numeric", tokenSize: 6, validityDurationInMinutes: 10, }) ``` ```json { "transaction": { "expires_at": "2026-08-28T10:10:00Z", "full_message": "Your Acme Bank code is {token}.", "id": "ot_", "initiated_at": "2026-08-28T10:00:00Z", "status": "pending_verification", "transmission": { "recipient": "+233241234567", "sender_id": "Acme", "sent_at": "2026-08-28T10:00:01Z", "sent_via": "sms", "status": "submitted" } } } ``` ## Verify OTP Record a verification attempt for a user-submitted token. An HTTP 200 response means the attempt was recorded; it does not mean the token matched. Authorize the user or action only when [`verificationAttempt.result.verdict`](https://typescript.inttegro.dev/v12.0.0) is [`Inttegro.OtpVerificationVerdicts.Pass`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpVerificationVerdicts.html#pass). ### Required attributes - `recipient` — `string` Phone number or bare email address that received the OTP. Must match the recipient and stored transport from initiation. - `token` — `string` The OTP token submitted by the user. This is the code they received by SMS or email. Cannot be blank or whitespace-only. - `transactionId` — `string` Typed ID returned from `/otp/initiate`, in the form `ot_`. The current transaction accepts at most five recorded attempts; after that, initiate a new transaction. ### Response Returns both [`transaction`](https://typescript.inttegro.dev/v12.0.0) and [`verificationAttempt`](https://typescript.inttegro.dev/v12.0.0). The attempt contains [`verificationAttempt.attemptedAt`](https://typescript.inttegro.dev/v12.0.0), [`verificationAttempt.id`](https://typescript.inttegro.dev/v12.0.0), [`verificationAttempt.presentedToken`](https://typescript.inttegro.dev/v12.0.0), [`verificationAttempt.recipient`](https://typescript.inttegro.dev/v12.0.0), and [`verificationAttempt.result`](https://typescript.inttegro.dev/v12.0.0). [`verificationAttempt.result.verdict`](https://typescript.inttegro.dev/v12.0.0) is [`Inttegro.OtpVerificationVerdicts.Pass`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpVerificationVerdicts.html#pass) or [`Inttegro.OtpVerificationVerdicts.Fail`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpVerificationVerdicts.html#fail); [`verificationAttempt.result.detail`](https://typescript.inttegro.dev/v12.0.0) is omitted for a passing result and explains a failed match when available. Treat [`verificationAttempt.presentedToken`](https://typescript.inttegro.dev/v12.0.0) as sensitive and exclude verification request and response bodies from logs. Matching and non-matching tokens both produce a successful response. Use [`verificationAttempt.result.verdict`](https://typescript.inttegro.dev/v12.0.0) to determine whether verification passed. **Request — POST /otp/verify** ```typescript import * as Inttegro from '@inttegro/inttegro-sdk' const inttegro = new Inttegro.InttegroClient({ apiKey: process.env.INTTEGRO_API_KEY!, }) const result = await inttegro.otp.verify({ recipient: "+233241234567", token: "", transactionId: "ot_", }) ``` A failed match still returns HTTP 200 with a [`Inttegro.OtpVerificationVerdicts.Fail`](https://typescript.inttegro.dev/v12.0.0/variables/types_otp.OtpVerificationVerdicts.html#fail) verdict. The API echoes the submitted value as [`verificationAttempt.presentedToken`](https://typescript.inttegro.dev/v12.0.0); the example uses a placeholder so no real code is exposed. ```json { "verification_attempt": { "attempted_at": "2026-08-28T10:03:00Z", "id": "ov_", "presented_token": "", "recipient": "+233241234567", "result": { "detail": "token_mismatch", "verdict": "fail" } }, "transaction": { "expires_at": "2026-08-28T10:10:00Z", "full_message": "Your Acme Bank code is {token}.", "id": "ot_", "initiated_at": "2026-08-28T10:00:00Z", "status": "pending_verification", "transmission": { "recipient": "+233241234567", "sender_id": "Acme", "sent_at": "2026-08-28T10:00:01Z", "sent_via": "sms", "status": "submitted" } } } ``` ## Lookup OTP transaction Retrieve details of an existing OTP transaction by its ID. Check transaction status, delivery state, and verification status. ### Required attributes - `transactionId` — `string` Typed OTP transaction ID to look up. ### Response Returns the transaction without the generated code or verification-attempt history. Optional cancellation and delivery-attempt fields are omitted when they do not apply. **Request — POST /otp/lookup** ```typescript import * as Inttegro from '@inttegro/inttegro-sdk' const inttegro = new Inttegro.InttegroClient({ apiKey: process.env.INTTEGRO_API_KEY!, }) const result = await inttegro.otp.lookup({ transactionId: "ot_", }) ``` ```json { "transaction": { "expires_at": "2026-08-28T10:10:00Z", "full_message": "Your Acme Bank code is {token}.", "id": "ot_", "initiated_at": "2026-08-28T10:00:00Z", "status": "pending_verification", "transmission": { "recipient": "+233241234567", "sender_id": "Acme", "sent_at": "2026-08-28T10:00:01Z", "sent_via": "sms", "status": "submitted" } } } ``` ## Related resources - [Create customer](https://studio.inttegro.com/machine/typescript/api/customers.md#create-customer) - Associate verified contact details with a customer record. - [Send Chime](https://studio.inttegro.com/machine/typescript/api/chimes.md#send-chime) - Send transactional SMS and email notifications after verification.