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
- The API works by redirecting the request to the telecom authentication gateway.
- It is processed in 2 parts. Initially, we check to see if the request is serviceable.
- If it is not, we fail it fast and the description for these errors is shared below.
- 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.
- 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.
- 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:
- Test Mode : https://api.sandbox.bureau.id/v2/auth
- Live Mode : https://api.bureau.id/v2/auth
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 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 |
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 | Type | Example | Description |
---|---|---|---|
clientId | Query Parameter, String, Mandatory | 8b50095f-1111-1111-1111-b04bc5405f96 | The API key shared by Bureau team. |
transactionId | Query Parameter, String. Mandatory | 82c744c4-82d2-4a12-92de-01fbc0ea53b5 | The 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. |
msisdn | Query Parameter, String. Mandatory | 779999999999 | Phone 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 | Type | Example | Description |
---|---|---|---|
X-Bureau-Auth-API-Key | Header Parameter, String, Mandatory | 8b50095f-1111-1111-1111-b04bc5405f96 | The API key shared by Bureau team. |
transactionId | Query Parameter, String. Mandatory | 82c744c4-82d2-4a12-92de-01fbc0ea53b5 | The 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.
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.
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.
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.
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