EasyOTP provides secure authentication via OTP, One-Tap (Magic Link) Login, and QR Code Scanning through developer-friendly REST APIs.
\nAlways use https://
\nNever log OTPs, ref_ids, or UIDs in production
\nStore UIDs received from the first successful authentication response and link them to customer accounts and Registered Mobile Number (RMN) in your DB for future seamless logins
\nQR flows are stateless; no cookies or sessions.
\nref_id is the anchor key to track each login attempt.
\nPolling frequency for /status every 2–3 seconds (not faster)
\nError Code : 400
\nCode : INVALID_PARAMS
\nMessage : Invalid parameters
\nWhen It Happens : Missing or malformed input
\nError Code : 400
\nCode : OTP_EXPIRED
\nMessage : OTP Expired
\nWhen It Happens : The OTP has expired
\nError Code : 400
\nCode : INVALID_OTP
\nMessage : Invalid OTP
\nWhen It Happens : The OTP entered is incorrect
\nError Code : 202
\nCode : REQUEST_PENDING
\nMessage : Request Pending
\nWhen It Happens : Auth flow not yet completed
\nError Code : 400
\nCode : REQUEST_EXPIRED
\nMessage : Request Expired
\nWhen It Happens : QR or session reference has expired/invalid
\nThis endpoint allows partners to authenticate users via One-Time Password (OTP) by submitting their phone number and country code.
\nMethod: POST
URL: https://easyotp.com/partner/api/v1/auth
The request body must be in JSON format and include the following parameters:
\nphone (string): The user's phone number. This is required for OTP generation.
\ncountry_code (string): The country code associated with the phone number. This should be in the format of a string, including the '+' sign (e.g., +1 for USA).
auth_type (string): The type of authentication to be performed. In this case, it should be set to otp.
Example Request Body:
\n{\n \"phone\": \"4155552671\",\n \"country_code\": \"+1\",\n \"auth_type\": \"otp\"\n}\n\nOn successful execution, the API will return a JSON response with the following structure:
\nsuccess (boolean): Indicates whether the authentication request was successful. A value of true signifies success.
ref_id (string): An identifier for the request, which may be used for tracking or further processing.
\nmessage (string): A message providing additional context about the request outcome. This may be empty.
\nExample Response:
\n{\n \"success\": true,\n \"ref_id\": \"f7e6c85504ce6e82442c770f7c8606f0\",\n \"message\": \"Authentication request sent to the user\"\n}\n\nEnsure that the phone number and country code are correctly formatted to avoid errors.
\nThe response will contain a success field that must be checked to confirm the authentication was successful.
This endpoint is primarily used for initiating the OTP process, and subsequent steps may be required for completing the authentication.
\nThis endpoint allows partners to authenticate users via One-Time Password (OTP) by submitting their phone number and country code.
\nMethod: POST
URL: https://easyotp.com/partner/api/v1/auth
The request body must be in JSON format and include the following parameters:
\nphone (string): The user's phone number. This is required for OTP generation.
\ncountry_code (string): The country code associated with the phone number. This should be in the format of a string, including the '+' sign (e.g., +1 for USA).
auth_type (string): The type of authentication to be performed. In this case, it should be set to otp.
Example Request Body:
\n{\n \"phone\": \"4155552671\",\n \"country_code\": \"+1\",\n \"auth_type\": \"otp\"\n}\n\nOn successful execution, the API will return a JSON response with the following structure:
\nsuccess (boolean): Indicates whether the authentication request was successful. A value of true signifies success.
ref_id (string): An identifier for the request, which may be used for tracking or further processing.
\nmessage (string): A message providing additional context about the request outcome. This may be empty.
\nExample Response:
\n{\n \"success\": true,\n \"ref_id\": \"f7e6c85504ce6e82442c770f7c8606f0\",\n \"message\": \"Authentication request sent to the user\"\n}\n\nEnsure that the phone number and country code are correctly formatted to avoid errors.
\nThe response will contain a success field that must be checked to confirm the authentication was successful.
This endpoint is primarily used for initiating the OTP process, and subsequent steps may be required for completing the authentication.
\nThis endpoint is used to authenticate a user via their phone number. It accepts a POST request with the necessary authentication parameters and returns a success response if the authentication is successful.
\nThe request body should be in JSON format and include the following parameters:
\nphone (string): The phone number of the user to authenticate. This should be provided in a valid format.
\ncountry_code (string): The country code associated with the phone number. It should include the '+' sign followed by the country code (e.g., +1 for USA).
\nauth_type (string): The type of authentication to be performed. In this case, the value should be set to \"one_tap\".
\nUpon a successful request, the API will return a JSON response with the following structure:
\nsuccess (boolean): Indicates whether the authentication was successful. A value of true means the authentication was successful.
ref_id (string): A reference ID associated with the authentication request. This may be used for tracking or further processing.
\nmessage (string): A message providing additional information about the request. This may be empty.
\nEnsure that the phone number and country code are correctly formatted to avoid authentication errors.
\nThe response will always include a success status, but additional information may vary based on the request's context.
\nTo check the Authentication status you'll need to call the Check Auth Status API. Polling frequency for /status every 2–3 seconds (not faster).
\nThis endpoint allows partners to authenticate users using a QR code method. By sending a POST request to this endpoint, you initiate the authentication process, which is particularly useful for scenarios where QR code scanning is implemented.
\nMethod: POST
\nURL: https://easyotp.com/partner/api/v1/auth
Content-Type: application/json
\nThe request body must be in JSON format and include the following parameter:
\n\"qr\" to indicate that the QR code authentication is being requested.Example Request Body:
\n{\n \"auth_type\": \"qr\"\n}\n\nUpon a successful request, the server responds with a JSON object containing the following fields:
\nsuccess (boolean): Indicates whether the authentication request was successful. A value of true confirms success.
ref_id (string): A unique identifier for the authentication request. This value may be used for tracking or further processing.
\nqr (string): The generated QR code data. This will be used by the client to display the dynamic QR code.
\nmessage (string): A message providing additional information about the request status. This may be empty or contain relevant details.
\nExample Response:
\n{\n \"success\": true,\n \"ref_id\": \"\",\n \"qr\": \"\",\n \"message\": \"\"\n}\n\nEnsure that the auth_type is correctly set to \"qr\" to avoid errors.
The response will provide the necessary information to proceed with the QR code scanning process.
\nTo check the Authentication status you'll need to call the Check Auth Status API. Polling frequency for /status every 2–3 seconds (not faster).
\nMethod: GET
Endpoint: https://easyotp.com/partner/api/v1/auth/status
Query Parameters:
\nref_id (string): A unique reference ID used to identify the authentication request.This endpoint is used to check the authentication status of a user based on a provided reference ID. By sending a GET request with the ref_id as a query parameter, you can retrieve the current status of the authentication process.
Status Code: 200 OK
Content-Type: application/json
Response Body:
\nsuccess (boolean): Indicates whether the request was successful.
status (string): The current status of the authentication.
user_data (object): Contains user-related information, which includes:
uid (string): User ID.
phone (string): Phone Number
user_consent (string): Granted
{\n \"success\": true,\n \"status\": \"\",\n \"user_data\": {\n \"uid\": \"\",\n }\n}\n\nThis API allows you to efficiently check the authentication status and retrieve relevant user data based on the reference ID provided.
\n","urlObject":{"protocol":"https","path":["partner","api","v1","auth","status"],"host":["easyotp","com"],"query":[{"key":"ref_id","value":"0a09c8844ba8f0936c20bd791130d6b6"}],"variable":[]}},"response":[{"id":"66b61aec-6d37-4ae1-892e-13c48464c755","name":"400 Invalid Request","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"$2y$10$sSXyQC1j6dTTZ2nsIsLGVuNpetbj.JJBZ.62zW7qtTOaMT89hOzTy","type":"text"}],"url":{"raw":"https://easyotp.com/partner/api/v1/auth/status?ref_id=0a09c8844ba8f0936c20bd791130d6b6a","protocol":"https","host":["easyotp","com"],"path":["partner","api","v1","auth","status"],"query":[{"key":"ref_id","value":"0a09c8844ba8f0936c20bd791130d6b6a"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 20 Aug 2025 03:02:22 GMT"},{"key":"Server","value":"Apache"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Debugbar-Time","value":"1755658942.663349"},{"key":"Debugbar-Link","value":"https://easyotp.com/?debugbar_time=1755658942.663349"},{"key":"Upgrade","value":"h2"},{"key":"Connection","value":"Upgrade, close"},{"key":"Content-Type","value":"application/json; charset=UTF-8"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_REQUEST\",\n \"message\": \"Invalid request\",\n \"details\": \"It's an invalid request. We can not process it.\"\n }\n}"},{"id":"9135b1d8-ca5e-4704-8f93-ed8dfcfb6e0a","name":"400 Request Expired","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"$2y$10$sSXyQC1j6dTTZ2nsIsLGVuNpetbj.JJBZ.62zW7qtTOaMT89hOzTy","type":"text"}],"url":{"raw":"https://easyotp.com/partner/api/v1/auth/status?ref_id=0a09c8844ba8f0936c20bd791130d6b6","protocol":"https","host":["easyotp","com"],"path":["partner","api","v1","auth","status"],"query":[{"key":"ref_id","value":"0a09c8844ba8f0936c20bd791130d6b6"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 20 Aug 2025 03:02:44 GMT"},{"key":"Server","value":"Apache"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Debugbar-Time","value":"1755658964.819529"},{"key":"Debugbar-Link","value":"https://easyotp.com/?debugbar_time=1755658964.819529"},{"key":"Upgrade","value":"h2"},{"key":"Connection","value":"Upgrade, close"},{"key":"Content-Type","value":"application/json; charset=UTF-8"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"status\": \"expired\",\n \"error\": {\n \"code\": \"REQUEST_EXPIRED\",\n \"message\": \"Request Expired\",\n \"details\": \"The request has been expired or invalid.\"\n }\n}"},{"id":"5561ff0a-a9ee-4b78-a30d-2c0d72ddf532","name":"202 Request Pending","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"$2y$10$sSXyQC1j6dTTZ2nsIsLGVuNpetbj.JJBZ.62zW7qtTOaMT89hOzTy","type":"text"}],"url":{"raw":"https://easyotp.com/partner/api/v1/auth/status?ref_id=4c5bde74a8f110656874902f07378009","protocol":"https","host":["easyotp","com"],"path":["partner","api","v1","auth","status"],"query":[{"key":"ref_id","value":"4c5bde74a8f110656874902f07378009"}]}},"status":"Accepted","code":202,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 20 Aug 2025 03:04:19 GMT"},{"key":"Server","value":"Apache"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Debugbar-Time","value":"1755659059.737296"},{"key":"Debugbar-Link","value":"https://easyotp.com/?debugbar_time=1755659059.737296"},{"key":"Upgrade","value":"h2"},{"key":"Connection","value":"Upgrade, close"},{"key":"Content-Type","value":"application/json; charset=UTF-8"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"status\": \"waiting\",\n \"error\": {\n \"code\": \"REQUEST_PENDING\",\n \"message\": \"Request Pending\",\n \"details\": \"The request is still pending.\"\n }\n}"},{"id":"4cd414b3-13b4-4365-bf19-e5c3910b396e","name":"200 Approved","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"$2y$10$sSXyQC1j6dTTZ2nsIsLGVuNpetbj.JJBZ.62zW7qtTOaMT89hOzTy","type":"text"}],"url":{"raw":"https://easyotp.com/partner/api/v1/auth/status?ref_id=eecca5b6365d9607ee5a9d336962c534","protocol":"https","host":["easyotp","com"],"path":["partner","api","v1","auth","status"],"query":[{"key":"ref_id","value":"eecca5b6365d9607ee5a9d336962c534"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 20 Aug 2025 03:05:43 GMT"},{"key":"Server","value":"Apache"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Debugbar-Time","value":"1755659143.409317"},{"key":"Debugbar-Link","value":"https://easyotp.com/?debugbar_time=1755659143.409317"},{"key":"Upgrade","value":"h2"},{"key":"Connection","value":"Upgrade, close"},{"key":"Content-Type","value":"application/json; charset=UTF-8"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"status\": \"approved\",\n \"user_data\": {\n \"uid\": \"987654jhkjhgf79dkjhskjdhf\",\n \"phone\": \"4155552671\",\n \"country_code\": \"+1\",\n }\n}"}],"_postman_id":"b75cbcc5-1b36-4ad7-ada9-4f8c69fe57fc"},{"name":"Verify OTP","id":"0dacfbd9-864d-415c-a1f9-01ea253cdf1a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"x-api-key","value":"$2y$10$sSXyQC1j6dTTZ2nsIsLGVuNpetbj.JJBZ.62zW7qtTOaMT89hOzTy","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"ref_id","value":"0a09c8844ba8f0936c20bd791130d6b6","type":"text"},{"key":"otp","value":"427262","type":"text"}]},"url":"https://easyotp.com/partner/api/v1/auth/verify","description":"This endpoint is used to verify a One-Time Password (OTP) associated with a specific reference ID. It is typically called after an OTP has been sent to a user for authentication purposes.
\nMethod: POST
\nURL: https://easyotp.com/partner/api/v1/auth/verify
Content-Type: application/x-www-form-urlencoded
ref_id (string, required): A reference identifier associated with the OTP request.
\notp (string, required): The One-Time Password that the user has received and is attempting to verify.
\nStatus Code: 200 OK
\nContent-Type: application/json
success (boolean): Indicates whether the OTP verification was successful.
\nstatus (string): A status message related to the verification process (may be empty).
\nuser_data (object): Contains information about the user if the verification is successful.
\nuid (string): User ID.
phone (string): Phone Number
user_consent (string): Granted
Ensure that the ref_id and otp parameters are correctly provided to avoid verification failures.
The response will include user data only if the OTP verification is successful.
\n