--- 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: "cURL" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/curl/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: 439 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 3668 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Generate and verify one-time passwords for secure authentication and verification flows. This cURL representation preserves HTTP paths and JSON wire names. ### 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` is `"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/curl/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 `"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 - `cancel_reason` — `string` Explanation for why this transaction was canceled. Omitted unless `transaction.status` is `"canceled"`. - `canceled_at` — `timestamp` When this transaction was canceled. Omitted unless `transaction.status` is `"canceled"`. - `expires_at` — `timestamp` When this token expires and can no longer be verified. - `full_message` — `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` — `string` Unique identifier for this transaction—use it to verify tokens and lookup transaction status. - `initiated_at` — `timestamp` When this transaction was created and token generation began. - `status` — `string` Current transaction status. Possible values are `"canceled"`, `"expired"`, `"pending"`, `"pending_delivery"`, `"pending_verification"`, and `"verified"`. `"pending_delivery"` means delivery-attempt fields are not available yet; `"pending_verification"` means the message was sent and the transaction is waiting for a verification attempt. - `transmission` Delivery details for the OTP message. Recipient and sender are always present; attempt fields are omitted until delivery begins. - `transmission.recipient` — `string` Normalized international phone number or bare email address targeted by delivery. - `transmission.sender_id` — `string` SMS sender identifier or noreply@inttegro.com for email OTP. - `transmission.sent_at` — `timestamp` When the message was sent. Omitted until the delivery attempt. - `transmission.sent_via` — `string` Delivery mechanism: `"sms"` or `"email"`. Omitted until the delivery attempt starts. - `transmission.status` — `string` Delivery status: `"submitted"`, `"delivered"`, or `"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. - `service_name` — `string` Service or application name substituted for `'{service}'` in the message template. Length: 2-20 characters. - `purpose` — `enum` — 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. - `token_size` — `integer` Generated token length. The current API requires a value from 5 through 10, inclusive. ### Optional attributes - `async_delivery` — `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 `"pending_delivery"`. - `message_template` — `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` Optional SMS gateway. Do not supply it for email OTP; email uses the configured default provider. - `transport` — `enum` Optional `"sms"` or `"email"`. A phone recipient selects SMS and an email recipient selects email when omitted. - `token_alphabet` — `string` 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` Predefined alphabet type for token generation. Supported values are `"alpha"`, `"alphanumeric"`, and `"numeric"`. If neither alphabet field is supplied, the default alphabet is alphanumeric. Mutually exclusive with `token_alphabet`. - `validity_duration_in_minutes` — `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`: `"submitted"` means the SMS message was submitted for delivery, `"delivered"` means delivery was confirmed, and `"failed"` means the delivery attempt failed. For email, `accepted` means SES accepted the send; it does not prove inbox delivery. **Request — POST /otp/initiate** ```bash curl https://api.inttegro.com/otp/initiate \ -H "Authorization: Bearer $INTTEGRO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: otp-login-67890" \ -d '{ "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` is `"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. - `transaction_id` — `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` and `verification_attempt`. The attempt contains `verification_attempt.attempted_at`, `verification_attempt.id`, `verification_attempt.presented_token`, `verification_attempt.recipient`, and `verification_attempt.result`. `verification_attempt.result.verdict` is `"pass"` or `"fail"`; `verification_attempt.result.detail` is omitted for a passing result and explains a failed match when available. Treat `verification_attempt.presented_token` 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` to determine whether verification passed. **Request — POST /otp/verify** ```bash response=$(curl https://api.inttegro.com/otp/verify \ -H "Authorization: Bearer $INTTEGRO_API_KEY" \ -H "Idempotency-Key: otp-verify-67890" \ -H "Content-Type: application/json" \ -d '{ "recipient": "+233241234567", "token": "", "transaction_id": "ot_" }') jq -e '.verification_attempt.result.verdict == "pass"' <<< "$response" ``` A failed match still returns HTTP 200 with a `"fail"` verdict. The API echoes the submitted value as `verification_attempt.presented_token`; 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` 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** ```bash curl https://api.inttegro.com/otp/lookup \ -H "Authorization: Bearer $INTTEGRO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "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/curl/api/customers.md#create-customer) - Associate verified contact details with a customer record. - [Send Chime](https://studio.inttegro.com/machine/curl/api/chimes.md#send-chime) - Send transactional SMS and email notifications after verification.