One Tap Login

Introduction:

This 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 also known as silent authentication 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 and provide a frictionless entry for their customers.

API Flow:

The entire journey can be reduced to two call's, More details are shared in the below documentation.

  • Initiate Authenticate - This request has to be made from the client device which contains the number that has to be verified.

  • Access User Info - This request has to be made to get the response of a certain user after it is verified. (An alternative to this is to subscribe to our webhooks and call backs will be sent to your servers post verification).
    Working of the API:

API Sequence Diagram

  1. The API works by redirecting the request to the telecom authentication gateway.
  2. It is processed in 2 parts. Initially, we check to see if the request is serviceable.
  3. If it is not, we fail it fast and the description for these errors is shared below.
  4. If it is serviceable, the request gets redirected to the respective telco, in case the request is processed by the telco, OK 200 is returned in the response and the user info API has to be called or a webhook can be used to know the authentication status.
  5. The Webhook URL is a URL defined by you to receive Asynchronous Callback Notifications, whenever an OTL has a status update to either: COMPLETED, EXPIRED, or ERROR.
  6. In case the request is not serviceable or telco is not able to process the request or the verification fails at the telco layer, you will have to redirect the user to an alternate mechanism.

API Gateway URL:

API Authentication

For authentication the API key has to be sent in the header with the key name as X-Bureau-Auth-API-Key. Contact the Bureau team for the authentication credentials.

Error Codes:

Bureau aims to make all transactions successful for its customers. However, errors might still occur in the ecosystem because of intermittent communication and technical issues at multiple hops. Hence, it becomes critical for businesses to identify the source of the error and the reason for the error. This enables you to minimize or fix errors to reduce any losses.

There can be two types of error codes

  • API Error Codes: These are the errors that occur because of incorrect parameters in the API Call.
  • Transaction Error Codes: These are the error codes that are shared with the transactions and can be used to take the next steps or decisions around the response.
Http Status CodeCodeMessageSuggested Action
200200101User verification failed
200200100User verification failed since providers failed to verifyAssume Authentication Failed and Backup to OTP
200200102User's ip doesn't belong to any supported provider
200200103User's mobile doesn't belong to any supported provider
202202100Awaiting provider acknowledgement
400400100Required parameters are missing or invalidRecheck the parameters
400400101Duplicate correlation idRetry with a Different Correlation ID
400400102Previous requests were not fulfilled or ended in errorsAssume Authentication Failed and Backup to OTP
400400103Cannot associate the correlation id with a flowCheck if Integration flow is working properly. Contact Bureau support
400400104Illegal application stateAssume Authentication Failed and Backup to OTP
400410100Auth state is expiredPlease re-initiate the auth flow
400400105Signals are empty or invalidCheck API docs
400400106Signals are invalid or template config is missingCheck API docs or contact Bureau support team
401401100Authorization parameters are missing or invalidCheck Authentication Parameters
500500100An internal error has occurredAssume Authentication Failed and Backup to OTP

Integration

API based

Initiate Authentication:

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.

curl --location --request GET 'https://api.sandbox.bureau.id/v2/auth/initiate?countryCode=IN&callbackUrl=https://enfktzdsbzye.x.pipedream.net/&clientId=8b50095f-1111-1111-1111-b04bc5405f96&transactionId=a15facc8-1111-1111-bac132&mobile=911111111111'
curl --location --request GET 'https://api.bureau.id/v2/auth/initiate?countryCode=IN&callbackUrl=https://enfktzdsbzye.x.pipedream.net/&clientId=8b50095f-1111-1111-1111-b04bc5405f96&transactionId=a15facc8-1111-1111-bac132&mobile=911111111111'
Request Parameter Description
Parameter TypeExampleDescription
clientIdQuery Parameter,
String, Mandatory
8b50095f-1111-1111-1111-b04bc5405f96The API key shared by Bureau team.
transactionIdQuery Parameter,
String. Mandatory
82c744c4-82d2-4a12-92de-01fbc0ea53b5The transaction ID that is generated by you for reference. This has to be generated from your backend and has to be unique for every request.
msisdnQuery Parameter,
String. Mandatory
779999999999Phone number with the country code.
UserInfo API call

This API call has to be made from your backend server.

curl --location --request GET 'https://api.sandbox.bureau.id/v2/auth/userinfo?transactionId=E1DA15EB-1111-1111-A9FA-2F1F65A9D046' \
--header 'Authorization: Basic MzNjMDBg0YzZWM3NTI1OWNiOA=='
curl --location --request GET 'https://api.bureau.id/v2/auth/userinfo?transactionId=E1DA15EB-1111-1111-A9FA-2F1F65A9D046' \
--header 'Authorization: Basic MzNjMDBg0YzZWM3NTI1OWNiOA=='
Request Parameters Description
Parameter TypeExampleDescription
X-Bureau-Auth-API-KeyHeader Parameter,
String, Mandatory
8b50095f-1111-1111-1111-b04bc5405f96The API key shared by Bureau team.
transactionIdQuery Parameter,
String. Mandatory
82c744c4-82d2-4a12-92de-01fbc0ea53b5The transaction ID that is generated by you for reference. This has to be generated from your backend and has to be unique for every request.

Android SDK Integration:

The SDK shared below can be used to make Initialise call. It handles the creation of session using mobile data even if wifi is connected. The SDK is only for invoking the initiating the request, to verify the authentication the userinfo API has to be called.

Link for Android SDK

iOS SDK Integration

The SDK shared below can be used to make Initialise call. It handles the creation of session using mobile data even if wifi is connected. The SDK is only for invoking the initiating the request, to verify the authentication the userinfo API has to be called.

Link for iOS SDK

Flutter bridge Integration

The bridge shared below can be used to make Initialise call. It handles the creation of session using mobile data even if wifi is connected. The SDK is only for invoking the initiating the request, to verify the authentication the userinfo API has to be called.

Link for bridge

React

The React App shared below can be used to make Initialise call. It handles the creation of session using mobile data even if wifi is connected. The SDK is only for invoking the initiating the request, to verify the authentication the userinfo API has to be called.

Link for sample react app

Testing in Sandbox

The API call has to be made to the sandbox URL https://api.sandbox.bureau.id/v2/auth

Testing Phone Numbers:

The following phone numbers can be used to simulate a success result, to simulate failure cases use any number with prefix 77 except the ones mentioned below.

779999999999
779999999998
779999999997
779999999996
779999999995
779999999994
779999999993
779999999992
779999999991
779999999990