--- 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: "Java" sdk_version: "v8.3.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/java/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: 496 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 5074 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Generate and verify one-time passwords for secure authentication and verification flows. This Java 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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) is [`OtpVerificationVerdict.PASS`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerificationVerdict.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/java/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 [`OtpVerificationVerdict.PASS`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerificationVerdict.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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` Explanation for why this transaction was canceled. Omitted unless [`transaction(…).status(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) is [`OtpStatus.CANCELED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#CANCELED). - [`canceledAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `timestamp` When this transaction was canceled. Omitted unless [`transaction(…).status(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) is [`OtpStatus.CANCELED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#CANCELED). - [`expiresAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `timestamp` When this token expires and can no longer be verified. - [`fullMessage(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` Unique identifier for this transaction—use it to verify tokens and lookup transaction status. - [`initiatedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `timestamp` When this transaction was created and token generation began. - [`status(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` Current transaction status. Possible values are [`OtpStatus.CANCELED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#CANCELED), [`OtpStatus.EXPIRED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#EXPIRED), [`OtpStatus.PENDING`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#PENDING), [`OtpStatus.PENDING_DELIVERY`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#PENDING_DELIVERY), [`OtpStatus.PENDING_VERIFICATION`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#PENDING_VERIFICATION), and [`OtpStatus.VERIFIED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#VERIFIED). [`OtpStatus.PENDING_DELIVERY`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#PENDING_DELIVERY) means delivery-attempt fields are not available yet; [`OtpStatus.PENDING_VERIFICATION`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#PENDING_VERIFICATION) means the message was sent and the transaction is waiting for a verification attempt. - [`transmission(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) Delivery details for the OTP message. Recipient and sender are always present; attempt fields are omitted until delivery begins. - [`transmission(…).recipient(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` Normalized international phone number or bare email address targeted by delivery. - [`transmission(…).senderId(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` SMS sender identifier or noreply@inttegro.com for email OTP. - [`transmission(…).sentAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `timestamp` When the message was sent. Omitted until the delivery attempt. - [`transmission(…).sentVia(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` Delivery mechanism: `"sms"` or `"email"`. Omitted until the delivery attempt starts. - [`transmission(…).status(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html) — `string` Delivery status: [`OtpTransmissionStatus.SUBMITTED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransmissionStatus.html#SUBMITTED), [`OtpTransmissionStatus.DELIVERED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransmissionStatus.html#DELIVERED), or [`OtpTransmissionStatus.FAILED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransmissionStatus.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(…)` — `Integer` 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 [`OtpStatus.PENDING_DELIVERY`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpStatus.html#PENDING_DELIVERY). - `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(…)` — `OtpAlphabetType` Predefined alphabet type for token generation. Supported values are [`OtpAlphabetType.ALPHA`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpAlphabetType.html#ALPHA), [`OtpAlphabetType.ALPHANUMERIC`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpAlphabetType.html#ALPHANUMERIC), and [`OtpAlphabetType.NUMERIC`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpAlphabetType.html#NUMERIC). If neither alphabet field is supplied, the default alphabet is alphanumeric. Mutually exclusive with `tokenAlphabet(…)`. - `validityDurationInMinutes(…)` — `Integer` 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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransaction.html): [`OtpTransmissionStatus.SUBMITTED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransmissionStatus.html#SUBMITTED) means the SMS message was submitted for delivery, [`OtpTransmissionStatus.DELIVERED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransmissionStatus.html#DELIVERED) means delivery was confirmed, and [`OtpTransmissionStatus.FAILED`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpTransmissionStatus.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** ```java import com.inttegro.Client; import com.inttegro.otp.InitiateOtpParams; import com.inttegro.otp.OtpAlphabetType; public class Example { public static void main(String[] args) throws Exception { var client = new Client(System.getenv("INTTEGRO_API_KEY")); var params = InitiateOtpParams.builder() .messageTemplate("Your {service} code is {token}.") .purpose("transaction_confirmation") .recipient("+233241234567") .sender("Acme") .serviceName("Acme Bank") .tokenAlphabetType(OtpAlphabetType.NUMERIC) .tokenSize(6) .validityDurationInMinutes(10) .build(); var result = client.otp().initiate(params); } } ``` ```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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) is [`OtpVerificationVerdict.PASS`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerificationVerdict.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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) and [`verificationAttempt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html). The attempt contains [`verificationAttempt(…).attemptedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html), [`verificationAttempt(…).id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html), [`verificationAttempt(…).presentedToken(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html), [`verificationAttempt(…).recipient(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html), and [`verificationAttempt(…).result(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html). [`verificationAttempt(…).result(…).verdict(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) is [`OtpVerificationVerdict.PASS`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerificationVerdict.html#PASS) or [`OtpVerificationVerdict.FAIL`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerificationVerdict.html#FAIL); [`verificationAttempt(…).result(…).detail(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) is omitted for a passing result and explains a failed match when available. Treat [`verificationAttempt(…).presentedToken(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) 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://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.html) to determine whether verification passed. **Request — POST /otp/verify** ```java import com.inttegro.Client; import com.inttegro.otp.VerifyOtpParams; public class Example { public static void main(String[] args) throws Exception { var client = new Client(System.getenv("INTTEGRO_API_KEY")); var params = VerifyOtpParams.builder() .recipient("+233241234567") .token("") .transactionId("ot_") .build(); var result = client.otp().verify(params); } } ``` A failed match still returns HTTP 200 with a [`OtpVerificationVerdict.FAIL`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerificationVerdict.html#FAIL) verdict. The API echoes the submitted value as [`verificationAttempt(…).presentedToken(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/otp/OtpVerification.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 - `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** ```java import com.inttegro.Client; import com.inttegro.otp.LookupOtpParams; public class Example { public static void main(String[] args) throws Exception { var client = new Client(System.getenv("INTTEGRO_API_KEY")); var params = LookupOtpParams.builder() .transactionId("ot_") .build(); var result = client.otp().lookup(params); } } ``` ```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/java/api/customers.md#create-customer) - Associate verified contact details with a customer record. - [Send Chime](https://studio.inttegro.com/machine/java/api/chimes.md#send-chime) - Send transactional SMS and email notifications after verification.