Send and check verification codes
A verification code goes through two stages. The Send verification code action delivers a six-digit code to a phone number or email address, and Momen stores the code against that recipient and scenario. When the user submits the code, it is checked either automatically by a built-in action such as Sign in, or by the Check verification code node in an Actionflow.
This guide covers three common tasks:
- Use a built-in scenario for sign-up, sign-in, password reset, and other account operations.
- Use a custom scenario to protect your own business logic, such as a prize draw.
- Deliver codes through your own SMS or email provider with a custom channel.
For a field-by-field reference, see Send verification code and Actionflow Nodes.
Key concepts
Scenarios
A scenario states what a code is for. The scenario used to check a code must match the one used to send it: a code sent with register fails when used to sign in.
Scenarios are the values of the system enum Verification code scenario and are managed under Action → Verification code → Scenarios. Momen ships six built-in scenarios, each checked automatically by its action:
| Scenario | Purpose | Checked by |
|---|---|---|
register | Sign up with a phone number or email | Sign up |
login | Sign in with a phone or email verification code | Sign in |
reset | Reset a password through a phone number or email | Reset password |
bind_account | Bind a phone number or email to the current account | Bind account |
unbind_account | Unbind a phone number or email from the current account | Unbind account |
delete | Delete the current account | Delete account |
Built-in scenarios cannot be changed. For any other purpose, add a custom scenario and check its codes with the Check verification code node in an Actionflow. Scenario names may contain only letters, digits, and underscores, and cannot start with a digit, for example prize_draw or withdraw_confirm.
Delivery channels
| Channel | Description |
|---|---|
| Built-in email | Momen sends the email for you. |
| Custom channel | Momen runs an Actionflow you configure, which delivers the code through your own provider. Use a custom channel to send codes by SMS. See Deliver codes through your own provider. |
Code rules
| Rule | Details |
|---|---|
| Format and lifetime | Six digits, valid for five minutes |
| Matching | The scenario and the recipient must both match the ones used when sending |
| Resending | Sending a new code to the same recipient for the same scenario immediately invalidates the previous one |
| Single use | A code is invalidated as soon as it is checked successfully |
| Cooldown | With built-in email, one code per recipient per scenario per minute; each scenario has its own cooldown |
Changes to scenarios or delivery channels under Action → Verification code take effect only after you sync backend changes.
Use a built-in scenario: sign in with an email code
This example builds email verification-code sign-in for a web app.
Enable the sign-in method
Open Action → Sign in and enable Email verification under Login methods. To send codes by SMS instead, enable Phone verification and set up a custom SMS channel.
If the matching sign-in method is disabled, sending the code fails.
Send the code
Add Communication → Send verification code to the On click trigger of the “Get code” button:
| Field | Value |
|---|---|
| Delivery channel | |
| Scenario | login |
| Send to | Value of the email input |
Add a 60-second countdown to the button so users do not request another code during the cooldown. See Verification code countdown timer.
Sign in and check the code
Add Sign in to the On click trigger of the “Sign in” button, choose email verification-code sign-in, and bind the email and code inputs.
Sign in checks the code against the login scenario. If the code is valid, the user is signed in and On success runs. If the code is wrong or has expired, On failure runs, where you can ask the user to request a new code.
Other built-in scenarios follow the same pattern. Only the scenario and the action change:
| Task | Scenario for Send verification code | Action that checks the code |
|---|---|---|
| Sign up with a phone number or email | register | Sign up |
| Recover a forgotten password | reset | Reset password |
| Bind a phone number or email | bind_account | Bind account |
| Unbind a phone number or email | unbind_account | Unbind account |
| Delete an account | delete | Delete account |
With the delete scenario, Send to is hidden. Momen sends the code to the phone number or email address bound to the signed-in user.
Use a custom scenario: confirm a prize draw by email
In this example, a signed-in user must enter a code sent to their own email address before each prize draw, which stops scripts from entering the draw automatically.
Add the scenario
Open Action → Verification code. In the last row of the Scenarios table, select Add scenario, name it prize_draw, and sync backend changes.
Send the code
Add Communication → Send verification code to the On click trigger of the “Get code” button:
| Field | Value |
|---|---|
| Delivery channel | |
| Scenario | prize_draw |
| Send to | The current user’s email address |
Built-in email also requires Email verification to be enabled under Action → Sign in.
Check the code and run the draw in an Actionflow
Create a synchronous Actionflow named “Prize draw” with one text input, code, and add these nodes in order:
- Current User: get the current user ID.
- Database: query the account table, filtered by that user ID, to get the user’s email address.
- Communication → Check verification code: set
scenariotoprize_draw, bindsendToto the email address from the previous step, and bindcodeto thecodeinput. - Condition: branch on the node’s
validoutput.- If
validis false, add a Throw node with the error message “The code is incorrect or has expired”. - If
validis true, continue to the draw.
- If
- Draw logic: query the prize pool, pick a prize at random, write the result, and return it as an output.
The Check verification code node does not fail when a code is wrong. It only sets valid to false. If nothing checks valid, the draw runs anyway.
Look up the email address inside the Actionflow from the current user. Do not accept it as an input from the page, or a user could pass an address they control and bypass the check on their own account.
Keep the draw in the same Actionflow, after the check. If the page calls one Actionflow to check the code and a second one to run the draw, anyone can call the second Actionflow directly and skip the check.
Call the Actionflow from the page
Add a Call Actionflow action to the On click trigger of the “Draw” button, select “Prize draw”, and bind its code input to the code input. Show the prize in On success and the error in On failure.
A verification code only proves that the user can receive mail at that address. It does not limit how often they can enter. Enforce rules such as “one draw per user per day” in the draw logic itself.
Do not use the Check verification code node on codes sent for built-in scenarios. A successful check invalidates the code, so Sign up, Sign in, and other actions will then reject it.
Deliver codes through your own provider
Add a custom channel to send codes by SMS, or to use your own sender, templates, and provider (such as Twilio). A custom channel is an Actionflow: after Momen generates a code, it runs the Actionflow, which is responsible for delivering the code.
Create a delivery Actionflow
Create an Actionflow with three text inputs: recipient, code, and scenario.
Add a node that sends the message, such as Send SMS - Twilio, or call your provider’s API. Bind the inputs to the node’s recipient and message fields.
The scenario input receives the scenario name, such as the built-in register or login, or a custom one like prize_draw. Use it to pick a different message template for each scenario.
Add a custom channel
Open Action → Verification code and add a channel in the last row of the Delivery channels table:
| Field | Description |
|---|---|
| Name | Channel name shown in the Delivery channel drop-down of Send verification code, such as “Twilio SMS” |
| Type | SMS or Email |
| Actionflow | The Actionflow created in the previous step |
| Actionflow inputs | In the data-binding menu, under Constant, bind the code’s recipient, the code, and the scenario to the matching Actionflow inputs |
Sync backend changes after saving. If your plan does not include custom channels, the page shows an upgrade prompt.
Select the channel in Send verification code
In Send verification code, open Delivery channel and select the new channel from the Custom group. Checking the code works the same way: the built-in action or the Check verification code node verifies it.
If the delivery Actionflow runs asynchronously, Send verification code reports success as soon as the Actionflow starts, and delivery failures inside it are not reported back to the page. Use a synchronous Actionflow if the page needs to know when delivery fails.
Troubleshooting
- The code is correct but the check fails. Check, in order:
- Whether the same scenario was used to send and check the code.
- Whether the user requested another code. A new code invalidates the previous one.
- Whether more than five minutes have passed.
- Whether the code has already been used, for example by a Check verification code node that ran earlier.
- Whether the same phone number or email address was used to send and check the code.
- “Too many requests” error. With built-in email, the same recipient can receive only one code per scenario per minute.
- Sending always fails. Make sure Phone verification or Email verification is enabled under Action → Sign in.
- Changes to scenarios or channels have no effect. Sync backend changes after editing them under Action → Verification code.
- Errors after renaming or deleting a custom scenario. Update any Send verification code actions and Check verification code nodes that use it. Momen asks you to confirm before deleting a scenario that is already deployed.
- Where does the account deletion code go? To the phone number (SMS channel) or email address (email channel) bound to the signed-in user.