Heroku with Nexmo Verify

by AdvaiyaLabs

GitHub Readme.md

Heroku with Nexmo Verify



In today’s digital world where data is under constant attack, passwords may get compromised through techniques like phishing, keystroke logging and brute force. In such scenarios, Heroku with Nexmo Verify via SMS is an efficient way to verify user access. As every country has its own communication compliance rules and regulations, so implementing Heroku with Nexmo Verify functionality via SMS at a global scale becomes challenging for the developers.

To implement Heroku with Nexmo Verify via SMS on a global scale over Heroku platform successfully, the developer community can use the Heroku with Nexmo Verify app that uses Nexmo Messaging APIs for user verification. This app can be deployed and integrated easily with any available programming languages for the phone verification and One-time-password (OTP).

Use Case

Enable Heroku developer community to implement Heroku with Two Factor Authentication (2FA) services via SMS using Nexmo messaging APIs, so they can easily deploy and integrate it with any platform (C#, Java, PHP).


  • Heroku subscription

  • Nexmo subscription and corresponding Nexmo API keys (Keys and Secret). To access the API keys, see the appendix section.

  • Make sure the provided information in configuration setting (Nexmo Key, Secret, etc.) are correct.


  • Phone number verification using the SMS

  • Easy integration with any application

  • Simple deployment as it requires less configuration

Steps to deploy Heroku with Nexmo Verify

  1. Login to Heroku platform.

  2. To setup Heroku with Nexmo Verify app, go to GitHub Repository:


  3. Click on Deploy to Heroku button. This will start the installation on Heroku under your subscription.

  4. Set an application name.

  5. Select a region where the application will deploy. By default, it is United States.

  6. Set the Nexmo application variable to send the SMS as shown below:

    • Extract the API and SECRET key from the Nexmo site. See the Appendix.

    • VERIFY_DURATION: The sent code will be valid for just some minutes given in the VERIFY_DURATION variable.

    • Click on Deploy for Free button to start the application.

  7. After successfully deploying, it shows two different buttons - Manage App and View.

  8. Click on View and copy the URL for further use.

Steps to use the Heroku with Nexmo Verify

While developing Heroku application using the above generated URL, you can apply the Heroku with Nexmo Verify functionality.

  1. Use the following URL in your application to send the verification code:


    • Replace the <heroku-app-url> with your Heroku public URL.

    • Verify will return a request id in JSON format and extract that request id for further use.

    • dst parameter is a destination phone number with country code to send the verification code. Replace the <phone_with_country_code> with the destination phone number.

    • This will send the OTP to the respective user.

  2. Submit the received OTP.

  3. To authenticate the OTP and request id, use the following URL:

    http://<heroku-app-url>/validate?code=<Mobile received code>&req_id=<request_id>

    • Replace the <heroku-app-url> with your Heroku public URL.

    • Replace the <request_id> to the request you get in your response.

    • Replace the <Mobile received code> with user entered OTP code, which he/she received on his/her phone as SMS.

    • Send request on validate end point with code and request id query string.

    • Returns JSON with a message and status (like if it is 0 that means successfully validated).

Check the status of request

To search requests' status that are terminated, still running or completed, use the following URL:

http://<heroku-app-url>/status? req_id=<request_id>

  1. Replace the <heroku-app-url> with your Heroku public URL.

  2. Replace the <request_id> to the request you get in your response.

  3. Send request on status end point with request id query string.

  4. Return the JSON of status information.

Steps to update the Heroku with Nexmo Verify app settings

  1. To update the application variables, select Nexmo application from Heroku Dashboard.

  2. Click on Settings and then click the Reveal Config Vars.

  3. Click on the Edit icon as shown below to update the variables.

  4. On the Edit config variable, a popup will be displayed. Update data and click on Save changes.


Nexmo API Keys

  • To access Nexmo keys, go to https://www.nexmo.com/ and sign-in.

  • On the top right corner, click on the Api Settings.

  • Key and Secret will display in the top bar as shown in the below image: