--- 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: "Ruby" sdk_version: "v10.0.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/ruby/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: 495 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 4918 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Generate and verify one-time passwords for secure authentication and verification flows. This Ruby 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 [`verification_attempt.result.verdict`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) is [`Inttegro::Otp::VerificationVerdict::PASS`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/VerificationVerdict.html#PASS-constant). #### 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/ruby/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::Otp::VerificationVerdict::PASS`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/VerificationVerdict.html#PASS-constant) 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 - [`cancel_reason`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` Explanation for why this transaction was canceled. Omitted unless [`transaction.status`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) is [`Inttegro::Otp::Status::CANCELED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#CANCELED-constant). - [`canceled_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `timestamp` When this transaction was canceled. Omitted unless [`transaction.status`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) is [`Inttegro::Otp::Status::CANCELED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#CANCELED-constant). - [`expires_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `timestamp` When this token expires and can no longer be verified. - [`full_message`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `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://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` Unique identifier for this transaction—use it to verify tokens and lookup transaction status. - [`initiated_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `timestamp` When this transaction was created and token generation began. - [`status`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` Current transaction status. Possible values are [`Inttegro::Otp::Status::CANCELED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#CANCELED-constant), [`Inttegro::Otp::Status::EXPIRED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#EXPIRED-constant), [`Inttegro::Otp::Status::PENDING`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#PENDING-constant), [`Inttegro::Otp::Status::PENDING_DELIVERY`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#PENDING_DELIVERY-constant), [`Inttegro::Otp::Status::PENDING_VERIFICATION`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#PENDING_VERIFICATION-constant), and [`Inttegro::Otp::Status::VERIFIED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#VERIFIED-constant). [`Inttegro::Otp::Status::PENDING_DELIVERY`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#PENDING_DELIVERY-constant) means delivery-attempt fields are not available yet; [`Inttegro::Otp::Status::PENDING_VERIFICATION`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#PENDING_VERIFICATION-constant) means the message was sent and the transaction is waiting for a verification attempt. - [`transmission`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) Delivery details for the OTP message. Recipient and sender are always present; attempt fields are omitted until delivery begins. - [`transmission.recipient`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` Normalized international phone number or bare email address targeted by delivery. - [`transmission.sender_id`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` SMS sender identifier or noreply@inttegro.com for email OTP. - [`transmission.sent_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `timestamp` When the message was sent. Omitted until the delivery attempt. - [`transmission.sent_via`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` Delivery mechanism: `'sms'` or `'email'`. Omitted until the delivery attempt starts. - [`transmission.status`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html) — `string` Delivery status: [`Inttegro::Otp::TransmissionStatus::SUBMITTED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/TransmissionStatus.html#SUBMITTED-constant), [`Inttegro::Otp::TransmissionStatus::DELIVERED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/TransmissionStatus.html#DELIVERED-constant), or [`Inttegro::Otp::TransmissionStatus::FAILED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/TransmissionStatus.html#FAILED-constant) 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` — wire-only International phone number that will receive SMS, such as `+233241234567`, or a bare email address. The transport is inferred unless specified. - `service_name` — `string` — wire-only Service or application name substituted for `'{service}'` in the message template. Length: 2-20 characters. - `purpose` — `enum` — required — wire-only 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. - `token_size` — `integer` — wire-only Generated token length. The current API requires a value from 5 through 10, inclusive. ### Optional attributes - `async_delivery` — `boolean` — wire-only 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::Otp::Status::PENDING_DELIVERY`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/Status.html#PENDING_DELIVERY-constant). - `message_template` — `string` — wire-only 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` — wire-only 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. - `token_alphabet` — `string` — wire-only Custom alphabet for token generation. Pass a string of characters to use (for example, `'0123456789ABCDEF'` for hexadecimal tokens). Mutually exclusive with `token_alphabet_type`—use one or the other, not both. - `token_alphabet_type` — `enum` — wire-only Predefined alphabet type for token generation. Supported values are [`Inttegro::Otp::AlphabetType::ALPHA`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/AlphabetType.html#ALPHA-constant), [`Inttegro::Otp::AlphabetType::ALPHANUMERIC`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/AlphabetType.html#ALPHANUMERIC-constant), and [`Inttegro::Otp::AlphabetType::NUMERIC`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/AlphabetType.html#NUMERIC-constant). If neither alphabet field is supplied, the default alphabet is alphanumeric. Mutually exclusive with `token_alphabet`. - `validity_duration_in_minutes` — `integer` — wire-only 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://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Transaction.html): [`Inttegro::Otp::TransmissionStatus::SUBMITTED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/TransmissionStatus.html#SUBMITTED-constant) means the SMS message was submitted for delivery, [`Inttegro::Otp::TransmissionStatus::DELIVERED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/TransmissionStatus.html#DELIVERED-constant) means delivery was confirmed, and [`Inttegro::Otp::TransmissionStatus::FAILED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/TransmissionStatus.html#FAILED-constant) means the delivery attempt failed. For email, `accepted` means SES accepted the send; it does not prove inbox delivery. **Request — POST /otp/initiate** ```ruby require "inttegro" client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY")) result = client.otp.initiate( message_template: "Your {service} code is {token}.", purpose: "transaction_confirmation", recipient: "+233241234567", sender: "Acme", service_name: "Acme Bank", token_alphabet_type: "numeric", token_size: 6, validity_duration_in_minutes: 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 [`verification_attempt.result.verdict`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) is [`Inttegro::Otp::VerificationVerdict::PASS`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/VerificationVerdict.html#PASS-constant). ### Required attributes - `recipient` — `string` — wire-only Phone number or bare email address that received the OTP. Must match the recipient and stored transport from initiation. - `token` — `string` — wire-only The OTP token submitted by the user. This is the code they received by SMS or email. Cannot be blank or whitespace-only. - `transaction_id` — `string` — wire-only 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://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) and [`verification_attempt`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html). The attempt contains [`verification_attempt.attempted_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html), [`verification_attempt.id`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html), [`verification_attempt.presented_token`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html), [`verification_attempt.recipient`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html), and [`verification_attempt.result`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html). [`verification_attempt.result.verdict`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) is [`Inttegro::Otp::VerificationVerdict::PASS`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/VerificationVerdict.html#PASS-constant) or [`Inttegro::Otp::VerificationVerdict::FAIL`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/VerificationVerdict.html#FAIL-constant); [`verification_attempt.result.detail`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) is omitted for a passing result and explains a failed match when available. Treat [`verification_attempt.presented_token`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) as sensitive and exclude verification request and response bodies from logs. Matching and non-matching tokens both produce a successful response. Use [`verification_attempt.result.verdict`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html) to determine whether verification passed. **Request — POST /otp/verify** ```ruby require "inttegro" client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY")) result = client.otp.verify( recipient: "+233241234567", token: "", transaction_id: "ot_" ) ``` A failed match still returns HTTP 200 with a [`Inttegro::Otp::VerificationVerdict::FAIL`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Otp/VerificationVerdict.html#FAIL-constant) verdict. The API echoes the submitted value as [`verification_attempt.presented_token`](https://ruby.inttegro.dev/v10.0.0/Inttegro/otp.Verification.html); 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 - `transaction_id` — `string` — wire-only 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** ```ruby require "inttegro" client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY")) result = client.otp.lookup( transaction_id: "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/ruby/api/customers.md#create-customer) - Associate verified contact details with a customer record. - [Send Chime](https://studio.inttegro.com/machine/ruby/api/chimes.md#send-chime) - Send transactional SMS and email notifications after verification.