![\"\"](\"https://onetaplogin.co/assets/images/logo.svg\"){kind=logo}
\n\nThis API document highlights the steps using which Businesses can integrate Bureau’s One-Tap Login solution for their Customers. The fundamental idea behind this product is to enable a smooth, SMS based One-time Password (OTP) less user journey that can help businesses verify the mobile phone number of their customers.
\nFor the best user experience, it’s recommended that this API integration is done at a user sign-up or login page, where a user is asked to enter their respective phone number to receive an OTP for verification.
\nBusinesses can integrate Bureau’s One-Tap login on the following platforms:
\nNote: One-Tap login functionality is currently not supported on Desktop Browsers
\nThe API integration is agnostic to application and platform in question and can easily enable Businesses to power the One-tap login product. This shall require integration for 2 APIs:
\nThe API works by redirecting the request to the telecom authentication gateway.
It is processed in 2 parts. Initially, we process it to check whether the request originates from the IP address & mobile number belonging to a carrier we support. If it does not, we fail it fast using error codes. You can check for the http status code in 400 or 500 to detect an error. If it does belong to a supported carrier, the response is controlled by respective telco gateways.
So you can process output to check if the http status code is in 200 series and, if yes, ignore the output. If the HTTP status code is 400 or 500 series, you can treat the authentication as non-serviceable and proceed with the backup.
\nTesting in Sandbox
\nSandbox URL: https://api.sandbox.bureau.id/v2/auth
\nFor simulating silent authentication in sandbox, you can use any of the following phone numbers:
\nBureau Phone Number Verification is a turnkey API product for mobile phone number verification. It confirms the ownership of a mobile phone number by verifying the possession of an active SIM card with the same number. A mobile data session is created to a unique URL for the purpose of this verification. Bureau then resolves a match between the phone number that the mobile network operator identifies as the owner of the mobile data session, and the phone number being verified.
\nWhenever anyone uses their mobile phone to make a phone call, send a text, or to access the internet, the provisioning mobile network operator has to first ascertain their identity. This is done through strong, cryptographic checks between the mobile operator and the SIM card in a user's mobile phone.
\nBureau leverages the identity that the carrier has established to verify if the provided credentials (phone number and SIM card) match. Only a valid, active SIM card can thus be identified by the carrier, thereby providing proof of possession of the phone number.
\nHere's how mobile phone number verification works through Bureau:
\nThe same steps may be repeated anytime you wish to re-verify a returning user.
\nFor the sake of efficiency and best possible user experience it will be preferable for an application to use the mobile network data connection and on-net authorization where possible. Use Https for all requests.
\nWe recommend developers do everything they can to avoid pop-up blockers.
Pop-up blockers do not block if the action of a button, or link is a direct window.open() and users will not need to disable pop-up blockers in their browsers
That means by way of example:
\n[](“/gf?profileSetup4=1®Id=0target=“changeMealItem\")
If window.open() is called in a success callback, or from a timer function for example, the browser is not opening a window as a result of a user action, but as a result of some programmatic activity - that’s when browsers block pop-ups
\nE.g., if you are using ajax to invoke APIs from web client, then set attribute ‘async’ to ‘false’ as illustrated below:
\n$.ajax({ url : url, type: 'GET', success : xxxxxxx, error : xxxxxxx, async: false })
Setting async to false will not let the flow break between when the user clicks the login-button (when discovery API gets invoked) and when authorize API is hit programmatically on the basis of discovery response.
\nDevelopers building native apps can process callbacks with webviews.
Webviews do not have to fill the entire screen – they can be simple 1 x 1 pixel views, where implementation is transparent to the user.
Enabling One Tap Login on Android, IOS & Web Integrations. Please follow the below guidelines to ensure full coverage and handle wifi connected devices:
\nThe code below can be used to make Initialise call. It takes care of creating session using mobile data even if wifi is connected.
\nBureauAuth bureauAuth = new BureauAuth.Builder()\n .mode(BureauAuth.Mode.Sandbox)\n .clientId(\"Your Client Id\")\n .build();\n //Other Options in builder are\n //timeOutInMs - total timeout\n //callbackUrl \n\nFor Handling wifi connected devices, Please download the source code from link below and follow given steps to enable Mobile Network and create https session from Mobile Network.
Source Code Link
let bureauObj = BureauAuth.Builder()\n .setClientId(clientId: \"e72a4414-a416-4872-8eea-6b51d6cd96e1\")\n .build()\n //Other Options in builder are\n //setTimeout - total timeout in seconds\n //setCallBackUrl\n //mode - sandbox and production\n\nOn Execution of silentAuth function, backend call can be made to get status of authentication
\n//Input init URL & final URL\n//No callbacks wait for a second and then call userinfo\nfunction silentAuth(correlationId, mobileNum, clientIDKey) {\n var initURL = \"https://api.sandbox.bureau.id/v2/auth/initiate?clientId=CLIENTIDSTRING&correlationId=CORRELATIONIDSTRING&msisdn=MSISDNSTRING\"\n var init = new Image();\n init.onload = startComplete;\n init.onerror = startComplete;\n initURL = initURL.replace(\"CORRELATIONIDSTRING\", correlationId)\n initURL = initURL.replace(\"CLIENTIDSTRING\", clientIDKey)\n initURL = initURL.replace(\"MSISDNSTRING\", mobileNum)\n init.src = initURL;\n function startComplete() {\n //callbacks are possible here. \n console.log(\"Process Complete\")\n }\n}\n\n| Http Status Code | Code | Message | Suggested Action |
| 200 | 200101 | User verification failed | |
| 200 | 200100 | User verification failed since providers failed to verify | Assume Authentication Failed and Backup to OTP |
| 200 | 200102 | User's ip doesn't belong to any supported provider | |
| 200 | 200103 | User's mobile doesn't belong to any supported provider | |
| 202 | 202100 | Awaiting provider acknowledgement | |
| 400 | 400100 | Required parameters are missing or invalid | Recheck the parameters |
| 400 | 400101 | Duplicate correlation id | Retry with a Different Correlation ID |
| 400 | 400102 | Previous requests were not fulfilled or ended in errors | Assume Authentication Failed and Backup to OTP |
| 400 | 400103 | Cannot associate the correlation id with a flow | Check if Integration flow is working properly. Contact Bureau support |
| 400 | 400104 | Illegal application state | Assume Authentication Failed and Backup to OTP |
| 400 | 410100 | Auth state is expired | Please re-initiate the auth flow |
| 400 | 400105 | Signals are empty or invalid | Check API docs |
| 400 | 400106 | Signals are invalid or template config is missing | Check API docs or contact Bureau support team |
| 401 | 401100 | Authorization parameters are missing or invalid | Check Authentication Parameters |
| 500 | 500100 | An internal error has occurred | Assume Authentication Failed and Backup to OTP |
Query Parameters
\n| Parameter\n | \nMandatory\n | \nDescription\n | \n
| transactionId\n | \nY\n | \nstring\n \nUniquely generated transaction ID\n | \n
| callbackUrl\n | \nN\n | \nstring\n \nClient Callback URL\n | \n
| clientId\n | \nY\n | \nstring\n \nBureau Generated ClientId\n | \n
| mobile\n | \nY\n | \nstring\n \nMobile Number captured from service user containing country code, E.164 format e.g 919958712345\n | \n
| countryCode\n | \nN\n | \nstring\n \nCountry code in ISO2 format e.g IN, US, etc.\n | \n
| scope\n | \nN\n | \nstring\n \nValue: \"share\"\n \nThe scope of the resource access to be authorized\n | \n
Pointers to be taken care of:
\nString. Mandatory. Identifier for your business. Present on your Dashboard
\n","type":"text/plain"},"key":"clientId","value":"acxvexxc2b-e5mlkwe-wmdwef-asqw"},{"description":{"content":"String. Mandatory. Transaction reference for the Initiate API call
\n","type":"text/plain"},"key":"transactionId","value":"bcac2be5-cd70-4a0d-bda2-c9c63cd2e982"},{"description":{"content":"String. Mandatory. Mobile number of the user along with the country code
\n","type":"text/plain"},"key":"mobile","value":"919999999999"},{"description":{"content":"String. Country code in ISO2 format
\n","type":"text/plain"},"key":"countryCode","value":"IN"},{"description":{"content":"String. Callback URL for passing the response of Authentication
\n","type":"text/plain"},"key":"callback","value":"https://callback-response/callback"}],"variable":[]}},"response":[{"id":"dd053ce3-572a-41cc-9ebd-74eb175e14e2","name":"/initiate","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.bureau.id/v2/auth/initiate?clientId=&transactionId=bcac2be5-cd70-4a0d-bda2-c9c63cd2e982&mobile=919999999999&countryCode=IN\n","protocol":"https","host":["api","bureau","id"],"path":["v2","auth","initiate"],"query":[{"key":"clientId","value":"","description":"The Client ID you receive from Bureau.id during onboarding."},{"key":"transactionId","value":"bcac2be5-cd70-4a0d-bda2-c9c63cd2e982","description":"A random string to correlate this transaction later."},{"key":"mobile","value":"919999999999","description":"The phone number (with country code) you want to use for this authentication request."},{"key":"countryCode","value":"IN\n"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"code\": \"string\",\n \"message\": \"string\",\n \"details\": \"string\"\n}"}],"_postman_id":"1c0f6a77-68c2-4eac-8206-b81bf0577f27"}],"id":"6713b73f-0e7f-468a-aada-96b13c6a1f53","description":"This API call is recommended to be implemented from the end-user’s end on device or front-end of the browser. This API call starts the authentication process by calling the API endpoint using User’s mobile-carrier network.
\n","_postman_id":"6713b73f-0e7f-468a-aada-96b13c6a1f53"},{"name":"Access User Information","item":[{"name":"/userInfo","id":"43d77fb6-059e-4563-b84b-e765d86de83f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-Bureau-Auth-API-Key","value":"","description":"The API key provided by Bureau.id during onboarding.
\n","type":"text"}],"url":"https://api.bureau.id/v2/auth/userinfo?transactionId=acxvexxc2b-e5mlkwe-wmdwef-asqw","description":"Query Parameters
\n| Parameter\n | \nMandatory\n | \nDescription\n | \n
| correlationId\n | \nY\n | \nstring\n \nTransaction ID sent across in the Initiate API call\n | \n
Header Parameters
\n| Parameter\n | \nMandatory\n | \nDescription\n | \n
| X-Bureau-Auth-API-Key\n | \nY\n | \nAPI Key provided by Bureau\n | \n
The correlation ID generated during the AuthInitiate phase.
\n","type":"text/plain"},"key":"transactionId","value":"acxvexxc2b-e5mlkwe-wmdwef-asqw"}],"variable":[]}},"response":[{"id":"d8f03cfe-b794-4fa3-88b0-d82fb27fd972","name":"/userInfo","originalRequest":{"method":"GET","header":[{"key":"X-Bureau-Auth-API-Key","value":"","description":"The API key provided by Bureau.id during onboarding.","type":"text"}],"url":{"raw":"https://api.bureau.id/v2/auth/userinfo?transactionId=","protocol":"https","host":["api","bureau","id"],"path":["v2","auth","userinfo"],"query":[{"key":"transactionId","value":"","description":"The correlation ID generated during the AuthInitiate phase."}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[],"cookie":[],"responseTime":null,"body":"{\n \"mobileNumber\": \"string\",\n \"country_code\": \"string\",\n \"status\":\"string\" // \"Success\", \"Failure\" or \"Pending\"\n}"}],"_postman_id":"43d77fb6-059e-4563-b84b-e765d86de83f"},{"name":"Callback Payload Structure","id":"52423673-eebb-487d-87ce-68b53080c45e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"correlationId\": \"a15facc8-xxxx-xxxx-062\",\n \"hurdleType\": \"SILENT_AUTH\",\n \"mobile\": \"779999999997\",\n \"signature\": {\n \"alg\": \"sha256\",\n \"data\": \"Edl4qqVm3sN7epBeehrYvahiA1rD8VEPonK3I7us3Dk=\"\n },\n \"status\": \"Success\",\n \"timestamp\": \"1678161010\"\n}","options":{"raw":{"language":"json"}}},"url":"This showcases the sample Callback payload that will be posted by us on the designated Callback URL passed in the Initiate API call.
\n| Parameter\n | \nMandatory\n | \nDescription\n | \n
| correlationId\n | \nY\n | \nstring\n \nUniquely generated Transaction ID passed in Initiate call\n | \n
| status\n | \nY\n | \nstring\n \nThis refers to the status of authentication request. Can be \"Success\"/\"Failure\" | \n
| signature\n | \nY\n | \nObject\n \nThe signature is the HMAC256 of \"CorrelationID:Status\" using the secret key.\n | \n
| signature.\"alg\"\n | \nY\n | \nstring\n \nAlgorithm used for creating signature\n | \n
| signature.\"data\"\n | \nY\n | \nstring\n \nValue of Signature\n | \n
This API helps initiating the OTP. The configuration ID shall be provided once the feature is enabled for your business.
\nThe Transaction ID needs to be generated from your end to track the result in the Validate OTP request.
\n","urlObject":{"protocol":"https","path":["v2","auth","otp"],"host":["api","bureau","id"],"query":[],"variable":[]}},"response":[{"id":"ca9808e5-1203-4d3e-bfda-7bf9a46cb323","name":"Initiate OTP - Success","originalRequest":{"method":"POST","header":[{"key":"X-Bureau-Auth-API-Key","value":"$your-secret-api-key-here$","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"otpConfigurationId\": \"4315cd42-db0f-4895-bb31-6fafc755c476\",\n \"mobile\": \"919780879196\"\n}"},"url":"https://api.bureau.id/v2/auth/otp"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"transactionId\": \"shekh-otp-2021-08-22-6-prod\",\n \"otpConfigurationId\": \"4315cd42-db0f-4895-bb31-6fafc755c476\",\n \"mobile\": \"919780879196\",\n \"otpStatus\": \"PENDING\",\n \"retryAttempts\": null,\n \"expireAt\": \"2021-08-24T11:22:51Z\",\n \"createdAt\": \"2021-08-24T11:17:51.313731176Z\",\n \"updatedAt\": \"2021-08-24T11:18:40.88350352Z\"\n}"},{"id":"717acfa4-440a-4cf3-ab9b-2b9f6a104582","name":"Initiate OTP - Failure","originalRequest":{"method":"POST","header":[{"key":"X-Bureau-Auth-API-Key","value":"$your-secret-api-key-here$","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"otpConfigurationId\": \"4315cd42-db0f-4895-bb31-6fafc755c476\",\n \"mobile\": \"919780879196\"\n}"},"url":"https://api.bureau.id/v2/auth/otp"},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"code\": \"DUPLICATE_TRANSACTION_ID\",\n \"description\": \"Duplicate transaction id\",\n \"metadata\": {\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"message\": \"\"\n }\n }\n}"}],"_postman_id":"9158ad08-49e7-4f08-9835-80dcbf34bd08"},{"name":"Validate OTP","id":"e50b24c6-0718-447b-98e1-600a12f09f93","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Bureau-Auth-API-Key","value":"$your-secret-api-key$","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"otpCode\": \"28613\"\n}"},"url":"https://api.bureau.id/v2/auth/otp/validate","description":"OTP Status variable can have 2 values: PENDING and VERIFIED.
\n","urlObject":{"protocol":"https","path":["v2","auth","otp","validate"],"host":["api","bureau","id"],"query":[],"variable":[]}},"response":[{"id":"8e3c06f3-c413-439d-a9b0-f09e0ac7de71","name":"Validate OTP - Success","originalRequest":{"method":"POST","header":[{"key":"X-Bureau-Auth-API-Key","value":"$your-secret-api-key$","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"otpCode\": \"28613\"\n}"},"url":"https://api.bureau.id/v2/auth/otp/validate"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"transactionId\": \"shekh-otp-2021-08-22-6-prod\",\n \"otpConfigurationId\": \"4315cd42-db0f-4895-bb31-6fafc755c476\",\n \"mobile\": \"919780879196\",\n \"otpStatus\": \"VERIFIED\",\n \"retryAttempts\": null,\n \"expireAt\": \"2021-08-24T11:22:51Z\",\n \"createdAt\": \"2021-08-24T11:17:51.313731176Z\",\n \"updatedAt\": \"2021-08-24T11:18:40.88350352Z\"\n}"},{"id":"8f4103d8-ba2a-4c80-a0ec-6b633761ca33","name":"Validate OTP - Failure","originalRequest":{"method":"POST","header":[{"key":"X-Bureau-Auth-API-Key","value":"$your-secret-api-key$","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"otpCode\": \"28613\"\n}"},"url":"https://api.bureau.id/v2/auth/otp/validate"},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"code\": \"USER_VERIFICATION_FAILURE\",\n \"description\": \"OTP not matched\",\n \"metadata\": {\n \"transactionId\": \"random-request-2021-08-27-10\",\n \"message\": \"\"\n }\n }\n}"}],"_postman_id":"e50b24c6-0718-447b-98e1-600a12f09f93"}],"id":"f7c1eaf0-dc9f-427c-8ca2-68213969948a","description":"Fallback OTP can be triggered by configuring 2 APIs on your end for Initiating and Validating the OTP. For enabling this feature, please reach out to Bureau Team.
\nThe configuration for the size of OTP, expiry time etc. can be set from the Dashboard itself. In addition to that, the following error codes shall be provided for tracking the fate of OTP Requests:
\n| HTTP Status Code\n\n | \nCode\n\n | \nDescription\n\n | \n
| 400\n\n | \nDUPLICATE_TRANSACTION_ID\n\n | \nDuplicate Transaction ID\n\n | \n
| 404\n\n | \nUSER_AUTHENTICATION_REQUEST_FAILURE\n\n | \nOTP configuration not found\n\n | \n
| 422\n\n | \nUSER_AUTHENTICATION_REQUEST_FAILURE\n\n | \nOTP max retry attempts reached\n\n | \n
| 422\n\n | \nUSER_VERIFICATION_FAILURE\n\n | \nOTP retry wait is in effect\n\n | \n
| 404\n\n | \nAUTH_STATE_EXPIRED\n\n | \nOTP expired or does not exist\n\n | \n
| 422\n\n | \nUSER_VERIFICATION_FAILURE\n\n | \nOTP already verified/not matched\n\n | \n
| 400\n\n | \nINVALID_SIGNALS\n\n | \nRequest body parameters are missing or invalid\n\n | \n
| 500\n\n | \nINTERNAL_ERROR\n\n | \nInternal server error\n\n | \n